faraday 0.6.0 → 0.9.0

data/lib/faraday/rack_builder.rb

@@ -0,0 +1,212 @@
+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|
+  #     builder.request  :url_encoded  # Faraday::Request::UrlEncoded
+  #     builder.adapter  :net_http     # Faraday::Adapter::NetHttp
+  #   end
+  class RackBuilder
+    attr_accessor :handlers
+
+    # Error raised when trying to modify the stack after calling `lock!`
+    class StackLocked < RuntimeError; end
+
+    # 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 }
+      }
+
+      attr_reader :name
+
+      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
+      end
+
+      def klass() @@constants[@name] end
+      def inspect() @name end
+
+      def ==(other)
+        if other.is_a? Handler
+          self.name == other.name
+        elsif other.respond_to? :name
+          klass == other
+        else
+          @name == other.to_s
+        end
+      end
+
+      def build(app)
+        klass.new(app, *@args, &@block)
+      end
+    end
+
+    def initialize(handlers = [])
+      @handlers = handlers
+      if block_given?
+        build(&Proc.new)
+      elsif @handlers.empty?
+        # default stack, if nothing else is configured
+        self.request :url_encoded
+        self.adapter Faraday.default_adapter
+      end
+    end
+
+    def build(options = {})
+      raise_if_locked
+      @handlers.clear unless options[:keep]
+      yield(self) if block_given?
+    end
+
+    def [](idx)
+      @handlers[idx]
+    end
+
+    # Locks the middleware stack to ensure no further modifications are possible.
+    def lock!
+      @handlers.freeze
+    end
+
+    def locked?
+      @handlers.frozen?
+    end
+
+    def use(klass, *args, &block)
+      if klass.is_a? Symbol
+        use_symbol(Faraday::Middleware, klass, *args, &block)
+      else
+        raise_if_locked
+        @handlers << self.class::Handler.new(klass, *args, &block)
+      end
+    end
+
+    def request(key, *args, &block)
+      use_symbol(Faraday::Request, key, *args, &block)
+    end
+
+    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)
+    end
+
+    ## methods to push onto the various positions in the stack:
+
+    def insert(index, *args, &block)
+      raise_if_locked
+      index = assert_index(index)
+      handler = self.class::Handler.new(*args, &block)
+      @handlers.insert(index, handler)
+    end
+
+    alias_method :insert_before, :insert
+
+    def insert_after(index, *args, &block)
+      index = assert_index(index)
+      insert(index + 1, *args, &block)
+    end
+
+    def swap(index, *args, &block)
+      raise_if_locked
+      index = assert_index(index)
+      @handlers.delete_at(index)
+      insert(index, *args, &block)
+    end
+
+    def delete(handler)
+      raise_if_locked
+      @handlers.delete(handler)
+    end
+
+    # Processes a Request into a Response by passing it through this Builder's
+    # middleware stack.
+    #
+    # connection - Faraday::Connection
+    # request    - Faraday::Request
+    #
+    # Returns a Faraday::Response.
+    def build_response(connection, request)
+      app.call(build_env(connection, request))
+    end
+
+    # 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
+        lock!
+        to_app(lambda { |env|
+          response = Response.new
+          response.finish(env) unless env.parallel?
+          env.response = response
+        })
+      end
+    end
+
+    def to_app(inner_app)
+      # last added handler is the deepest and thus closest to the inner app
+      @handlers.reverse.inject(inner_app) { |app, handler| handler.build(app) }
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && @handlers == other.handlers
+    end
+
+    def dup
+      self.class.new(@handlers.dup)
+    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.
+    def build_env(connection, request)
+      Env.new(request.method, request.body,
+        connection.build_exclusive_url(request.path, request.params),
+        request.options, request.headers, connection.ssl,
+        connection.parallel_manager)
+    end
+
+    private
+
+    def raise_if_locked
+      raise StackLocked, "can't modify middleware stack after making a request" if locked?
+    end
+
+    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
+end

data/lib/faraday/request/authorization.rb

@@ -0,0 +1,42 @@
+module Faraday
+  class Request::Authorization < Faraday::Middleware
+    KEY = "Authorization".freeze unless defined? KEY
+
+    # Public
+    def self.header(type, token)
+      case token
+      when String, Symbol
+        "#{type} #{token}"
+      when Hash
+        build_hash(type.to_s, token)
+      else
+        raise ArgumentError, "Can't build an Authorization #{type} header from #{token.inspect}"
+      end
+    end
+
+    # Internal
+    def self.build_hash(type, hash)
+      offset = KEY.size + type.size + 3
+      comma = ",\n#{' ' * offset}"
+      values = []
+      hash.each do |key, value|
+        values << "#{key}=#{value.to_s.inspect}"
+      end
+      "#{type} #{values * comma}"
+    end
+
+    def initialize(app, type, token)
+      @header_value = self.class.header(type, token)
+      super(app)
+    end
+
+    # Public
+    def call(env)
+      unless env.request_headers[KEY]
+        env.request_headers[KEY] = @header_value
+      end
+      @app.call(env)
+    end
+  end
+end
+

data/lib/faraday/request/basic_authentication.rb

@@ -0,0 +1,13 @@
+require 'base64'
+
+module Faraday
+  class Request::BasicAuthentication < Request.load_middleware(:authorization)
+    # Public
+    def self.header(login, pass)
+      value = Base64.encode64([login, pass].join(':'))
+      value.gsub!("\n", '')
+      super(:Basic, value)
+    end
+  end
+end
+

data/lib/faraday/request/instrumentation.rb

@@ -0,0 +1,36 @@
+module Faraday
+  class Request::Instrumentation < Faraday::Middleware
+    class Options < Faraday::Options.new(:name, :instrumenter)
+      def name
+        self[:name] ||= 'request.faraday'
+      end
+
+      def instrumenter
+        self[:instrumenter] ||= ActiveSupport::Notifications
+      end
+    end
+
+    # Public: Instruments requests using Active Support.
+    #
+    # Measures time spent only for synchronous requests.
+    #
+    # Examples
+    #
+    #   ActiveSupport::Notifications.subscribe('request.faraday') do |name, starts, ends, _, env|
+    #     url = env[:url]
+    #     http_method = env[:method].to_s.upcase
+    #     duration = ends - starts
+    #     $stderr.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
+    #   end
+    def initialize(app, options = nil)
+      super(app)
+      @name, @instrumenter = Options.from(options).values_at(:name, :instrumenter)
+    end
+
+    def call(env)
+      @instrumenter.instrument(@name, env) do
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/faraday/request/multipart.rb

@@ -1,46 +1,46 @@
+require File.expand_path("../url_encoded", __FILE__)
+
 module Faraday
   class Request::Multipart < Request::UrlEncoded
     self.mime_type = 'multipart/form-data'.freeze
-    DEFAULT_BOUNDARY = "-----------RubyMultipartPost".freeze
+    DEFAULT_BOUNDARY = "-----------RubyMultipartPost".freeze unless defined? DEFAULT_BOUNDARY
 
     def call(env)
       match_content_type(env) do |params|
-        env[:request] ||= {}
-        env[:request][:boundary] ||= DEFAULT_BOUNDARY
-        env[:request_headers][CONTENT_TYPE] += ";boundary=#{env[:request][:boundary]}"
-        env[:body] = create_multipart(env, params)
+        env.request.boundary ||= DEFAULT_BOUNDARY
+        env.request_headers[CONTENT_TYPE] += "; boundary=#{env.request.boundary}"
+        env.body = create_multipart(env, params)
       end
       @app.call env
     end
 
     def process_request?(env)
       type = request_type(env)
-      env[:body].respond_to?(:each_key) and !env[:body].empty? and (
-        (type.empty? and has_multipart?(env[:body])) or
+      env.body.respond_to?(:each_key) and !env.body.empty? and (
+        (type.empty? and has_multipart?(env.body)) or
         type == self.class.mime_type
       )
     end
 
-    def has_multipart?(body)
-      body.values.each do |val|
-        if val.respond_to?(:content_type)
-          return true
-        elsif val.respond_to?(:values)
-          return true if has_multipart?(val)
+    def has_multipart?(obj)
+      # string is an enum in 1.8, returning list of itself
+      if obj.respond_to?(:each) && !obj.is_a?(String)
+        (obj.respond_to?(:values) ? obj.values : obj).each do |val|
+          return true if (val.respond_to?(:content_type) || has_multipart?(val))
         end
       end
       false
     end
 
     def create_multipart(env, params)
-      boundary = env[:request][:boundary]
+      boundary = env.request.boundary
       parts = process_params(params) do |key, value|
         Faraday::Parts::Part.new(boundary, key, value)
       end
       parts << Faraday::Parts::EpiloguePart.new(boundary)
 
       body = Faraday::CompositeReadIO.new(parts)
-      env[:request_headers]['Content-Length'] = body.length.to_s
+      env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
       return body
     end
 

data/lib/faraday/request/retry.rb

@@ -0,0 +1,118 @@
+module Faraday
+  # Catches exceptions and retries each request a limited number of times.
+  #
+  # By default, it retries 2 times and handles only timeout exceptions. It can
+  # be configured with an arbitrary number of retries, a list of exceptions to
+  # handle, a retry interval, a percentage of randomness to add to the retry
+  # interval, and a backoff factor.
+  #
+  # Examples
+  #
+  #   Faraday.new do |conn|
+  #     conn.request :retry, max: 2, interval: 0.05,
+  #                          interval_randomness: 0.5, backoff_factor: 2
+  #                          exceptions: [CustomException, 'Timeout::Error']
+  #     conn.adapter ...
+  #   end
+  #
+  # This example will result in a first interval that is random between 0.05 and 0.075 and a second
+  # interval that is random between 0.1 and 0.15
+  #
+  class Request::Retry < Faraday::Middleware
+    class Options < Faraday::Options.new(:max, :interval, :interval_randomness, :backoff_factor, :exceptions)
+      def self.from(value)
+        if Fixnum === value
+          new(value)
+        else
+          super(value)
+        end
+      end
+
+      def max
+        (self[:max] ||= 2).to_i
+      end
+
+      def interval
+        (self[:interval] ||= 0).to_f
+      end
+
+      def interval_randomness
+        (self[:interval_randomness] ||= 0).to_i
+      end
+
+      def backoff_factor
+        (self[:backoff_factor] ||= 1).to_f
+      end
+
+      def exceptions
+        Array(self[:exceptions] ||= [Errno::ETIMEDOUT, 'Timeout::Error',
+                                     Error::TimeoutError])
+      end
+
+    end
+
+    # Public: Initialize middleware
+    #
+    # Options:
+    # max                 - Maximum number of retries (default: 2)
+    # interval            - Pause in seconds between retries (default: 0)
+    # interval_randomness - The maximum random interval amount expressed
+    #                       as a float between 0 and 1 to use in addition to the
+    #                       interval. (default: 0)
+    # backoff_factor      - The amount to multiple each successive retry's
+    #                       interval amount by in order to provide backoff
+    #                       (default: 1)
+    # exceptions          - The list of exceptions to handle. Exceptions can be
+    #                       given as Class, Module, or String. (default:
+    #                       [Errno::ETIMEDOUT, Timeout::Error,
+    #                       Error::TimeoutError])
+    def initialize(app, options = nil)
+      super(app)
+      @options = Options.from(options)
+      @errmatch = build_exception_matcher(@options.exceptions)
+    end
+
+    def sleep_amount(retries)
+      retry_index = @options.max - retries
+      current_interval = @options.interval * (@options.backoff_factor ** retry_index)
+      random_interval  = rand * @options.interval_randomness.to_f * @options.interval
+      current_interval + random_interval
+    end
+
+    def call(env)
+      retries = @options.max
+      request_body = env[:body]
+      begin
+        env[:body] = request_body # after failure env[:body] is set to the response body
+        @app.call(env)
+      rescue @errmatch
+        if retries > 0
+          retries -= 1
+          sleep sleep_amount(retries + 1)
+          retry
+        end
+        raise
+      end
+    end
+
+    # Private: construct an exception matcher object.
+    #
+    # An exception matcher for the rescue clause can usually be any object that
+    # responds to `===`, but for Ruby 1.8 it has to be a Class or Module.
+    def build_exception_matcher(exceptions)
+      matcher = Module.new
+      (class << matcher; self; end).class_eval do
+        define_method(:===) do |error|
+          exceptions.any? do |ex|
+            if ex.is_a? Module
+              error.is_a? ex
+            else
+              error.class.to_s == ex.to_s
+            end
+          end
+        end
+      end
+      matcher
+    end
+  end
+end

data/lib/faraday/request/token_authentication.rb

@@ -0,0 +1,15 @@
+module Faraday
+  class Request::TokenAuthentication < Request.load_middleware(:authorization)
+    # Public
+    def self.header(token, options = nil)
+      options ||= {}
+      options[:token] = token
+      super(:Token, options)
+    end
+
+    def initialize(app, token, options = nil)
+      super(app, token, options)
+    end
+  end
+end
+

data/lib/faraday/request/url_encoded.rb

@@ -1,6 +1,6 @@
 module Faraday
   class Request::UrlEncoded < Faraday::Middleware
-    CONTENT_TYPE = 'Content-Type'.freeze
+    CONTENT_TYPE = 'Content-Type'.freeze unless defined? CONTENT_TYPE
 
     class << self
       attr_accessor :mime_type
@@ -9,27 +9,26 @@ module Faraday
 
     def call(env)
       match_content_type(env) do |data|
-        env[:body] = Faraday::Utils.build_nested_query data
+        params = Faraday::Utils::ParamsHash[data]
+        env.body = params.to_query(env.params_encoder)
       end
       @app.call env
     end
-    
+
     def match_content_type(env)
-      type = request_type(env)
-      
       if process_request?(env)
-        env[:request_headers][CONTENT_TYPE] ||= self.class.mime_type
-        yield env[:body] unless env[:body].respond_to?(:to_str)
+        env.request_headers[CONTENT_TYPE] ||= self.class.mime_type
+        yield(env.body) unless env.body.respond_to?(:to_str)
       end
     end
 
     def process_request?(env)
       type = request_type(env)
-      env[:body] and (type.empty? or type == self.class.mime_type)
+      env.body and (type.empty? or type == self.class.mime_type)
     end
 
     def request_type(env)
-      type = env[:request_headers][CONTENT_TYPE].to_s
+      type = env.request_headers[CONTENT_TYPE].to_s
       type = type.split(';', 2).first if type.index(';')
       type
     end

data/lib/faraday/request.rb

@@ -9,34 +9,54 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
-  class Request < Struct.new(:path, :params, :headers, :body)
-    extend AutoloadHelper
+  class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
+    extend MiddlewareRegistry
 
-    autoload_all 'faraday/request',
-      :JSON       => 'json',
-      :UrlEncoded => 'url_encoded',
-      :Multipart  => 'multipart'
+    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_lookup_modules \
-      :json        => :JSON,
-      :url_encoded => :UrlEncoded,
-      :multipart   => :Multipart
+    def self.create(request_method)
+      new(request_method).tap do |request|
+        yield(request) if block_given?
+      end
+    end
 
-    def self.run(connection, request_method)
-      req = create
-      yield req if block_given?
-      req.run(connection, request_method)
+    # Public: Replace params, preserving the existing hash type
+    def params=(hash)
+      if params
+        params.replace hash
+      else
+        super
+      end
     end
 
-    def self.create
-      req = new(nil, {}, {}, nil)
-      yield req if block_given?
-      req
+    # Public: Replace request headers, preserving the existing hash type
+    def headers=(hash)
+      if headers
+        headers.replace hash
+      else
+        super
+      end
     end
 
-    def url(path, params = {})
-      self.path   = path
-      self.params = params
+    def url(path, params = nil)
+      if path.respond_to? :query
+        if query = path.query
+          path = path.dup
+          path.query = nil
+        end
+      else
+        path, query = path.split('?', 2)
+      end
+      self.path = path
+      self.params.merge_query query, options.params_encoder
+      self.params.update(params) if params
     end
 
     def [](key)
@@ -50,7 +70,7 @@ module Faraday
     # ENV Keys
     # :method - a symbolized request method (:get, :post)
     # :body   - the request body that will eventually be converted to a string.
-    # :url    - Addressable::URI instance of the URI for the current request.
+    # :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
@@ -63,29 +83,10 @@ module Faraday
     #     :user       - Proxy server username
     #     :password   - Proxy server password
     # :ssl - Hash of options for configuring SSL requests.
-    def to_env_hash(connection, request_method)
-      env_headers = connection.headers.dup
-      env_params  = connection.params.dup
-      connection.merge_headers(env_headers, headers)
-      connection.merge_params(env_params,  params)
-
-      { :method           => request_method,
-        :body             => body,
-        :url              => connection.build_url(path, env_params),
-        :request_headers  => env_headers,
-        :parallel_manager => connection.parallel_manager,
-        :request          => connection.options.merge(:proxy => connection.proxy),
-        :ssl              => connection.ssl}
-    end
-
-    def run(connection, request_method)
-      app = lambda { |env|
-        response = Response.new
-        response.finish(env) unless env[:parallel_manager]
-        env[:response] = response
-      }
-      env = to_env_hash(connection, request_method)
-      connection.builder.to_app(app).call(env)
+    def to_env(connection)
+      Env.new(method, body, connection.build_exclusive_url(path, params),
+        options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end
+

data/lib/faraday/response/logger.rb

@@ -15,14 +15,14 @@ module Faraday
     def_delegators :@logger, :debug, :info, :warn, :error, :fatal
 
     def call(env)
-      info "#{env[:method]} #{env[:url].to_s}"
-      debug('request') { dump_headers env[:request_headers] }
+      info "#{env.method} #{env.url.to_s}"
+      debug('request') { dump_headers env.request_headers }
       super
     end
 
     def on_complete(env)
-      info('Status') { env[:status].to_s }
-      debug('response') { dump_headers env[:response_headers] }
+      info('Status') { env.status.to_s }
+      debug('response') { dump_headers env.response_headers }
     end
 
     private