faraday 0.8.11 → 0.9.0.rc1

data/lib/faraday/adapter/test.rb

@@ -28,46 +28,45 @@ module Faraday
           @stack.empty?
         end
 
-        def match(request_method, path, body)
+        def match(request_method, path, headers, body)
           return false if !@stack.key?(request_method)
           stack = @stack[request_method]
           consumed = (@consumed[request_method] ||= [])
-          path = normalize_path(path)
 
-          if stub = matches?(stack, path, body)
+          if stub = matches?(stack, path, headers, body)
             consumed << stack.delete(stub)
             stub
           else
-            matches?(consumed, path, body)
+            matches?(consumed, path, headers, body)
           end
         end
 
-        def get(path, &block)
-          new_stub(:get, path, &block)
+        def get(path, headers = {}, &block)
+          new_stub(:get, path, headers, &block)
         end
 
-        def head(path, &block)
-          new_stub(:head, path, &block)
+        def head(path, headers = {}, &block)
+          new_stub(:head, path, headers, &block)
         end
 
-        def post(path, body=nil, &block)
-          new_stub(:post, path, body, &block)
+        def post(path, body=nil, headers = {}, &block)
+          new_stub(:post, path, headers, body, &block)
         end
 
-        def put(path, body=nil, &block)
-          new_stub(:put, path, body, &block)
+        def put(path, body=nil, headers = {}, &block)
+          new_stub(:put, path, headers, body, &block)
         end
 
-        def patch(path, body=nil, &block)
-          new_stub(:patch, path, body, &block)
+        def patch(path, body=nil, headers = {}, &block)
+          new_stub(:patch, path, headers, body, &block)
         end
 
-        def delete(path, &block)
-          new_stub(:delete, path, &block)
+        def delete(path, headers = {}, &block)
+          new_stub(:delete, path, headers, &block)
         end
 
-        def options(path, &block)
-          new_stub(:options, path, &block)
+        def options(path, headers = {}, &block)
+          new_stub(:options, path, headers, &block)
         end
 
         # Raises an error if any of the stubbed calls have not been made.
@@ -85,40 +84,34 @@ module Faraday
 
         protected
 
-        def new_stub(request_method, path, body=nil, &block)
-          (@stack[request_method] ||= []) << Stub.new(normalize_path(path), body, block)
+        def new_stub(request_method, path, headers = {}, body=nil, &block)
+          normalized_path = Faraday::Utils.normalize_path(path)
+          (@stack[request_method] ||= []) << Stub.new(normalized_path, headers, body, block)
         end
 
-        def matches?(stack, path, body)
-          stack.detect { |stub| stub.matches?(path, body) }
-        end
-
-        # ensure leading + trailing slash
-        def normalize_path(path)
-          path = '/' + path if path.index('/') != 0
-          path = path.sub('?', '/?')
-          path = path + '/' unless $&
-          path.gsub('//', '/')
+        def matches?(stack, path, headers, body)
+          stack.detect { |stub| stub.matches?(path, headers, body) }
         end
       end
 
-      class Stub < Struct.new(:path, :params, :body, :block)
-        def initialize(full, body, block)
+      class Stub < Struct.new(:path, :params, :headers, :body, :block)
+        def initialize(full, headers, body, block)
           path, query = full.split('?')
           params = query ?
             Faraday::Utils.parse_nested_query(query) :
             {}
-          super path, params, body, block
+          super path, params, headers, body, block
         end
 
-        def matches?(request_uri, request_body)
+        def matches?(request_uri, request_headers, request_body)
           request_path, request_query = request_uri.split('?')
           request_params = request_query ?
             Faraday::Utils.parse_nested_query(request_query) :
             {}
           request_path == path &&
             params_match?(request_params) &&
-            (body.to_s.size.zero? || request_body == body)
+            (body.to_s.size.zero? || request_body == body) &&
+            headers_match?(request_headers)
         end
 
         def params_match?(request_params)
@@ -127,6 +120,12 @@ module Faraday
           end
         end
 
+        def headers_match?(request_headers)
+          headers.keys.all? do |key|
+            request_headers[key] == headers[key]
+          end
+        end
+
         def to_s
           "#{path} #{body}"
         end
@@ -146,7 +145,7 @@ module Faraday
         super
         normalized_path = Faraday::Utils.normalize_path(env[:url])
 
-        if stub = stubs.match(env[:method], normalized_path, env[:body])
+        if stub = stubs.match(env[:method], normalized_path, env.request_headers, env[:body])
           env[:params] = (query = env[:url].query) ?
             Faraday::Utils.parse_nested_query(query)  :
             {}

data/lib/faraday/adapter/typhoeus.rb

@@ -40,11 +40,12 @@ module Faraday
           :method  => method,
           :body    => env[:body],
           :headers => env[:request_headers],
-          :disable_ssl_peer_verification => (env[:ssl] && !env[:ssl].fetch(:verify, true))
+          :disable_ssl_peer_verification => (env[:ssl] && env[:ssl].disable?)
 
         configure_ssl     req, env
         configure_proxy   req, env
         configure_timeout req, env
+        configure_socket  req, env
 
         req.on_complete do |resp|
           if resp.timed_out?
@@ -55,15 +56,6 @@ module Faraday
             end
           end
 
-          case resp.curl_return_code
-          when 0
-            # everything OK
-          when 7
-            raise Error::ConnectionFailed, resp.curl_error_message
-          else
-            raise Error::ClientError, resp.curl_error_message
-          end
-
           save_response(env, resp.code, resp.body) do |response_headers|
             response_headers.parse resp.headers
           end
@@ -78,8 +70,8 @@ module Faraday
         ssl = env[:ssl]
 
         req.ssl_version = ssl[:version]          if ssl[:version]
-        req.ssl_cert    = ssl[:client_cert_file] if ssl[:client_cert_file]
-        req.ssl_key     = ssl[:client_key_file]  if ssl[:client_key_file]
+        req.ssl_cert    = ssl[:client_cert] if ssl[:client_cert]
+        req.ssl_key     = ssl[:client_key]  if ssl[:client_key]
         req.ssl_cacert  = ssl[:ca_file]          if ssl[:ca_file]
         req.ssl_capath  = ssl[:ca_path]          if ssl[:ca_path]
       end
@@ -102,6 +94,12 @@ module Faraday
         req.connect_timeout = (env_req[:open_timeout] * 1000)          if env_req[:open_timeout]
       end
 
+      def configure_socket(req, env)
+        if bind = request_options(env)[:bind]
+          req.interface = bind[:host]
+        end
+      end
+
       def request_options(env)
         env[:request]
       end

data/lib/faraday/autoload.rb

@@ -0,0 +1,87 @@
+require 'faraday'
+
+module Faraday
+  # Internal: Adds the ability for other modules to manage autoloadable
+  # constants.
+  module AutoloadHelper
+    # Internal: Registers the constants to be auto loaded.
+    #
+    # prefix  - The String require prefix.  If the path is inside Faraday, then
+    #           it will be prefixed with the root path of this loaded Faraday
+    #           version.
+    # options - Hash of Symbol => String library names.
+    #
+    # Examples.
+    #
+    #   Faraday.autoload_all 'faraday/foo',
+    #     :Bar => 'bar'
+    #
+    #   # requires faraday/foo/bar to load Faraday::Bar.
+    #   Faraday::Bar
+    #
+    #
+    # Returns nothing.
+    def autoload_all(prefix, options)
+      if prefix =~ /^faraday(\/|$)/i
+        prefix = File.join(Faraday.root_path, prefix)
+      end
+      options.each do |const_name, path|
+        autoload const_name, File.join(prefix, path)
+      end
+    end
+
+    # Internal: Loads each autoloaded constant.  If thread safety is a concern,
+    # wrap this in a Mutex.
+    #
+    # Returns nothing.
+    def load_autoloaded_constants
+      constants.each do |const|
+        const_get(const) if autoload?(const)
+      end
+    end
+
+    # Internal: Filters the module's contents with those that have been already
+    # autoloaded.
+    #
+    # Returns an Array of Class/Module objects.
+    def all_loaded_constants
+      constants.map { |c| const_get(c) }.
+        select { |a| a.respond_to?(:loaded?) && a.loaded? }
+    end
+  end
+
+  class Adapter
+    extend AutoloadHelper
+    autoload_all 'faraday/adapter',
+      :NetHttp           => 'net_http',
+      :NetHttpPersistent => 'net_http_persistent',
+      :Typhoeus          => 'typhoeus',
+      :EMSynchrony       => 'em_synchrony',
+      :EMHttp            => 'em_http',
+      :Patron            => 'patron',
+      :Excon             => 'excon',
+      :Test              => 'test',
+      :Rack              => 'rack',
+      :HTTPClient        => 'httpclient'
+  end
+
+  class Request
+    extend AutoloadHelper
+    autoload_all 'faraday/request',
+      :UrlEncoded => 'url_encoded',
+      :Multipart => 'multipart',
+      :Retry => 'retry',
+      :Timeout => 'timeout',
+      :Authorization => 'authorization',
+      :BasicAuthentication => 'basic_authentication',
+      :TokenAuthentication => 'token_authentication'
+  end
+
+  class Response
+    extend AutoloadHelper
+    autoload_all 'faraday/response',
+      :RaiseError => 'raise_error',
+      :Logger     => 'logger'
+  end
+end
+

data/lib/faraday/connection.rb

@@ -1,24 +1,49 @@
-require 'cgi'
-require 'set'
-require 'forwardable'
-require 'uri'
-
-Faraday.require_libs 'builder', 'request', 'response', 'utils'
-
 module Faraday
+  # Public: Connection objects manage the default properties and the middleware
+  # stack for fulfilling an HTTP request.
+  #
+  # Examples
+  #
+  #   conn = Faraday::Connection.new 'http://sushi.com'
+  #
+  #   # GET http://sushi.com/nigiri
+  #   conn.get 'nigiri'
+  #   # => #<Faraday::Response>
+  #
   class Connection
+    # A Set of allowed HTTP verbs.
     METHODS = Set.new [:get, :post, :put, :delete, :head, :patch, :options]
-    METHODS_WITH_BODIES = Set.new [:post, :put, :patch, :options]
 
-    attr_reader :params, :headers, :url_prefix, :builder, :options, :ssl, :parallel_manager
+    # Public: Returns a Hash of URI query unencoded key/value pairs.
+    attr_reader :params
+
+    # Public: Returns a Hash of unencoded HTTP header key/value pairs.
+    attr_reader :headers
+
+    # Public: Returns a URI with the prefix used for all requests from this
+    # Connection.  This includes a default host name, scheme, port, and path.
+    attr_reader :url_prefix
+
+    # Public: Returns the Faraday::Builder for this Connection.
+    attr_reader :builder
+
+    # Public: Returns a Hash of the request options.
+    attr_reader :options
+
+    # Public: Returns a Hash of the SSL options.
+    attr_reader :ssl
+
+    # Public: Returns the parallel manager for this Connection.
+    attr_reader :parallel_manager
+
+    # Public: Sets the default parallel manager for this connection.
     attr_writer :default_parallel_manager
 
     # Public: Initializes a new Faraday::Connection.
     #
     # url     - URI or String base URL to use as a prefix for all
     #           requests (optional).
-    # options - Hash of settings that will be applied to every request made
-    #           from this Connection (default: {}).
+    # options - Hash or Faraday::ConnectionOptions.
     #           :url     - URI or String base URL (default: "http:/").
     #           :params  - Hash of URI query unencoded key/value pairs.
     #           :headers - Hash of unencoded HTTP header key/value pairs.
@@ -29,77 +54,79 @@ module Faraday
     #                     :uri      - URI or String
     #                     :user     - String (optional)
     #                     :password - String (optional)
-    def initialize(url = nil, options = {})
+    def initialize(url = nil, options = nil)
       if url.is_a?(Hash)
-        options = url
-        url     = options[:url]
+        options = ConnectionOptions.from(url)
+        url     = options.url
+      else
+        options = ConnectionOptions.from(options)
       end
-      @headers = Utils::Headers.new
-      @params  = Utils::ParamsHash.new
-      @options = options[:request] || {}
-      @ssl     = options[:ssl]     || {}
 
       @parallel_manager = nil
-      @default_parallel_manager = options[:parallel_manager]
+      @headers = Utils::Headers.new
+      @params  = Utils::ParamsHash.new
+      @options = options.request
+      @ssl = options.ssl
+      @default_parallel_manager = options.parallel_manager
 
-      @builder = options[:builder] || begin
+      @builder = options.builder || begin
         # pass an empty block to Builder so it doesn't assume default middleware
-        block = block_given?? Proc.new {|b| } : nil
-        Builder.new(&block)
+        options.new_builder(block_given? ? Proc.new { |b| } : nil)
       end
 
       self.url_prefix = url || 'http:/'
 
-      @params.update options[:params]   if options[:params]
-      @headers.update options[:headers] if options[:headers]
+      @params.update(options.params)   if options.params
+      @headers.update(options.headers) if options.headers
 
-      @proxy = nil
-      proxy(options.fetch(:proxy) {
-        uri = ENV['http_proxy']
-        if uri && !uri.empty?
-          uri = 'http://' + uri if uri !~ /^http/i
-          uri
-        end
-      })
+      proxy(options.fetch(:proxy) { ENV['http_proxy'] })
 
       yield self if block_given?
 
       @headers[:user_agent] ||= "Faraday v#{VERSION}"
     end
 
-    # Public: Replace default query parameters.
+    # Public: Sets the Hash of URI query unencoded key/value pairs.
     def params=(hash)
       @params.replace hash
     end
 
-    # Public: Replace default request headers.
+    # Public: Sets the Hash of unencoded HTTP header key/value pairs.
     def headers=(hash)
       @headers.replace hash
     end
 
     extend Forwardable
-    def_delegators :builder, :build, :use, :request, :response, :adapter
-
-    # The "rack app" wrapped in middleware. All requests are sent here.
-    #
-    # The builder is responsible for creating the app object. After this,
-    # the builder gets locked to ensure no further modifications are made
-    # to the middleware stack.
-    #
-    # Returns an object that responds to `call` and returns a Response.
-    def app
-      @app ||= begin
-        builder.lock!
-        builder.to_app(lambda { |env|
-          # the inner app that creates and returns the Response object
-          response = Response.new
-          response.finish(env) unless env[:parallel_manager]
-          env[:response] = response
-        })
-      end
-    end
 
-    # get/head/delete(url, params, headers)
+    def_delegators :builder, :build, :use, :request, :response, :adapter, :app
+
+    # Public: Makes an HTTP request without a body.
+    #
+    # url     - The optional String base URL to use as a prefix for all
+    #           requests.  Can also be the options Hash.
+    # params  - Hash of URI query unencoded key/value pairs.
+    # headers - Hash of unencoded HTTP header key/value pairs.
+    #
+    # Examples
+    #
+    #   conn.get '/items', {:page => 1}, :accept => 'application/json'
+    #   conn.head '/items/1'
+    #
+    #   # ElasticSearch example sending a body with GET.
+    #   conn.get '/twitter/tweet/_search' do |req|
+    #     req.headers[:content_type] = 'application/json'
+    #     req.params[:routing] = 'kimchy'
+    #     req.body = JSON.generate(:query => {...})
+    #   end
+    #
+    # Yields a Faraday::Response for further request customizations.
+    # Returns a Faraday::Response.
+    #
+    # Signature
+    #
+    #   <verb>(url = nil, params = nil, headers = nil)
+    #
+    # verb - An HTTP verb: get, head, or delete.
     %w[get head delete].each do |method|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method}(url = nil, params = nil, headers = nil)
@@ -111,7 +138,32 @@ module Faraday
       RUBY
     end
 
-    # post/put/patch(url, body, headers)
+    # Public: Makes an HTTP request with a body.
+    #
+    # url     - The optional String base URL to use as a prefix for all
+    #           requests.  Can also be the options Hash.
+    # body    - The String body for the request.
+    # headers - Hash of unencoded HTTP header key/value pairs.
+    #
+    # Examples
+    #
+    #   conn.post '/items', 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', ...)
+    #   end
+    #
+    # Yields a Faraday::Response for further request customizations.
+    # Returns a Faraday::Response.
+    #
+    # Signature
+    #
+    #   <verb>(url = nil, body = nil, headers = nil)
+    #
+    # verb - An HTTP verb: post, put, or patch.
     %w[post put patch].each do |method|
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method}(url = nil, body = nil, headers = nil, &block)
@@ -120,16 +172,60 @@ module Faraday
       RUBY
     end
 
+    # Public: Sets up the Authorization header with these credentials, encoded
+    # with base64.
+    #
+    # login - The authentication login.
+    # pass  - The authentication password.
+    #
+    # Examples
+    #
+    #   conn.basic_auth 'Aladdin', 'open sesame'
+    #   conn.headers['Authorization']
+    #   # => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
+    #
+    # Returns nothing.
     def basic_auth(login, pass)
       headers[Faraday::Request::Authorization::KEY] =
         Faraday::Request::BasicAuthentication.header(login, pass)
     end
 
+    # Public: Sets up the Authorization header with the given token.
+    #
+    # token   - The String token.
+    # options - Optional Hash of extra token options.
+    #
+    # Examples
+    #
+    #   conn.token_auth 'abcdef', :foo => 'bar'
+    #   conn.headers['Authorization']
+    #   # => "Token token=\"abcdef\",
+    #               foo=\"bar\""
+    #
+    # Returns nothing.
     def token_auth(token, options = nil)
       headers[Faraday::Request::Authorization::KEY] =
         Faraday::Request::TokenAuthentication.header(token, options)
     end
 
+    # Public: Sets up a custom Authorization header.
+    #
+    # type  - The String authorization type.
+    # token - The String or Hash token.  A String value is taken literally, and
+    #         a Hash is encoded into comma separated key/value pairs.
+    #
+    # Examples
+    #
+    #   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\""
+    #
+    # Returns nothing.
     def authorization(type, token)
       headers[Faraday::Request::Authorization::KEY] =
         Faraday::Request::Authorization.header(type, token)
@@ -153,10 +249,19 @@ module Faraday
       end
     end
 
+    # Public: Determine if this Faraday::Connection can make parallel requests.
+    #
+    # Returns true or false.
     def in_parallel?
       !!@parallel_manager
     end
 
+    # Public: Sets up the parallel manager to make a set of requests.
+    #
+    # manager - The parallel manager that this Connection's Adapter uses.
+    #
+    # Yields a block to execute multiple requests.
+    # Returns nothing.
     def in_parallel(manager = nil)
       @parallel_manager = manager || default_parallel_manager {
         warn "Warning: `in_parallel` called but no parallel-capable adapter on Faraday stack"
@@ -169,43 +274,23 @@ module Faraday
       @parallel_manager = nil
     end
 
+    # Public: Gets or Sets the Hash proxy options.
     def proxy(arg = nil)
       return @proxy if arg.nil?
-
-      @proxy = if arg.is_a? Hash
-        uri = self.class.URI arg.fetch(:uri) { raise ArgumentError, "missing :uri" }
-        arg.merge :uri => uri
-      else
-        uri = self.class.URI(arg)
-        {:uri => uri}
-      end
-
-      with_uri_credentials(uri) do |user, password|
-        @proxy[:user]     ||= user
-        @proxy[:password] ||= password
-      end
-
-      @proxy
-    end
-
-    # normalize URI() behavior across Ruby versions
-    def self.URI(url)
-      if url.respond_to?(:host)
-        url
-      elsif url.respond_to?(:to_str)
-        Kernel.URI(url)
-      else
-        raise ArgumentError, "bad argument (expected URI object or URI string)"
-      end
+      @proxy = ProxyOptions.from(arg)
     end
 
     def_delegators :url_prefix, :scheme, :scheme=, :host, :host=, :port, :port=
     def_delegator :url_prefix, :path, :path_prefix
 
-    # Parses the giving url with URI and stores the individual
+    # Public: Parses the giving url with URI and stores the individual
     # components in this connection.  These components serve as defaults for
     # requests made by this connection.
     #
+    # url - A String or URI.
+    #
+    # Examples
+    #
     #   conn = Faraday::Connection.new { ... }
     #   conn.url_prefix = "https://sushi.com/api"
     #   conn.scheme      # => https
@@ -213,11 +298,12 @@ module Faraday
     #
     #   conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
     #
-    def url_prefix=(url)
-      uri = @url_prefix = self.class.URI(url)
+    # Returns the parsed URI from teh given input..
+    def url_prefix=(url, encoder = nil)
+      uri = @url_prefix = Utils.URI(url)
       self.path_prefix = uri.path
 
-      params.merge_query(uri.query)
+      params.merge_query(uri.query, encoder)
       uri.query = nil
 
       with_uri_credentials(uri) do |user, password|
@@ -228,7 +314,12 @@ module Faraday
       uri
     end
 
-    # Ensures that the path prefix always has a leading but no trailing slash
+    # Public: Sets the path prefix and ensures that it always has a leading
+    # but no trailing slash.
+    #
+    # value - A String.
+    #
+    # Returns the new String path prefix.
     def path_prefix=(value)
       url_prefix.path = if value
         value = value.chomp '/'
@@ -237,6 +328,14 @@ module Faraday
       end
     end
 
+    # Builds and runs the Faraday::Request.
+    #
+    # method  - The Symbol HTTP method.
+    # url     - The String or URI to access.
+    # body    - The String body
+    # headers - Hash of unencoded HTTP header key/value pairs.
+    #
+    # Returns a Faraday::Response.
     def run_request(method, url, body, headers)
       if !METHODS.include?(method)
         raise ArgumentError, "unknown http method: #{method}"
@@ -249,11 +348,10 @@ module Faraday
         yield req if block_given?
       end
 
-      env = request.to_env(self)
-      self.app.call(env)
+      builder.build_response(self, request)
     end
 
-    # Internal: Creates and configures the request object.
+    # Creates and configures the request object.
     #
     # Returns the new Request.
     def build_request(method)
@@ -279,9 +377,9 @@ module Faraday
     def build_url(url, extra_params = nil)
       uri = build_exclusive_url(url)
 
-      query_values = self.params.dup.merge_query(uri.query)
+      query_values = self.params.dup.merge_query(uri.query, options.params_encoder)
       query_values.update extra_params if extra_params
-      uri.query = query_values.empty? ? nil : query_values.to_query
+      uri.query = query_values.empty? ? nil : query_values.to_query(options.params_encoder)
 
       uri
     end
@@ -301,18 +399,16 @@ module Faraday
         base.path = base.path + '/'  # ensure trailing slash
       end
       uri = url ? base + url : base
-      uri.query = params.to_query if params
+      uri.query = params.to_query(options.params_encoder) if params
       uri.query = nil if uri.query and uri.query.empty?
       uri
     end
 
+    # Internal: Creates a duplicate of this Faraday::Connection.
+    #
+    # Returns a Faraday::Connection.
     def dup
-      self.class.new(build_url(''),
-                     :headers => headers.dup,
-                     :params => params.dup,
-                     :builder => builder.dup,
-                     :ssl => ssl.dup,
-                     :request => options.dup)
+      self.class.new(build_url(''), :headers => headers.dup, :params => params.dup, :builder => builder.dup, :ssl => ssl.dup)
     end
 
     # Internal: Yields username and password extracted from a URI if they both exist.
@@ -323,3 +419,4 @@ module Faraday
     end
   end
 end
+