faraday 0.8.11 → 0.9.0.rc1

data/lib/faraday/{builder.rb → rack_builder.rb}

@@ -1,11 +1,12 @@
 module Faraday
-  # Possibly going to extend this a bit.
+  # 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 Builder
+  #   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!`
@@ -14,15 +15,19 @@ module Faraday
     # borrowed from ActiveSupport::Dependencies::Reference &
     # ActionDispatch::MiddlewareStack::Middleware
     class Handler
+      @@constants_mutex = Mutex.new
       @@constants = Hash.new { |h, k|
-        h[k] = k.respond_to?(:constantize) ? k.constantize : Object.const_get(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
-        @@constants[@name] = klass if klass.respond_to?(:name)
+        if klass.respond_to?(:name)
+          @@constants_mutex.synchronize { @@constants[@name] = klass }
+        end
         @args, @block = args, block
       end
 
@@ -65,19 +70,6 @@ module Faraday
       @handlers[idx]
     end
 
-    def ==(other)
-      other.is_a?(self.class) && @handlers == other.handlers
-    end
-
-    def dup
-      self.class.new(@handlers.dup)
-    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
-
     # Locks the middleware stack to ensure no further modifications are possible.
     def lock!
       @handlers.freeze
@@ -136,6 +128,71 @@ module Faraday
       @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

data/lib/faraday/request.rb

@@ -10,25 +10,16 @@ module Faraday
   #   end
   #
   class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
-    extend AutoloadHelper
     extend MiddlewareRegistry
 
-    autoload_all 'faraday/request',
-      :UrlEncoded => 'url_encoded',
-      :Multipart => 'multipart',
-      :Retry => 'retry',
-      :Timeout => 'timeout',
-      :Authorization => 'authorization',
-      :BasicAuthentication => 'basic_authentication',
-      :TokenAuthentication => 'token_authentication'
-
-    register_middleware \
-      :url_encoded => :UrlEncoded,
-      :multipart => :Multipart,
-      :retry => :Retry,
-      :authorization => :Authorization,
-      :basic_auth => :BasicAuthentication,
-      :token_auth => :TokenAuthentication
+    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']
 
     def self.create(request_method)
       new(request_method).tap do |request|
@@ -60,7 +51,7 @@ module Faraday
         path, query = path.split('?', 2)
       end
       self.path = path
-      self.params.merge_query query
+      self.params.merge_query query, options.params_encoder
       self.params.update(params) if params
     end
 
@@ -89,13 +80,9 @@ module Faraday
     #     :password   - Proxy server password
     # :ssl - Hash of options for configuring SSL requests.
     def to_env(connection)
-      { :method           => method,
-        :body             => body,
-        :url              => connection.build_exclusive_url(path, params),
-        :request_headers  => headers,
-        :parallel_manager => connection.parallel_manager,
-        :request          => options,
-        :ssl              => connection.ssl}
+      Env.new(method, body, connection.build_exclusive_url(path, params),
+        options, headers, connection.ssl, connection.parallel_manager)
     end
   end
 end
+

data/lib/faraday/request/authorization.rb

@@ -1,6 +1,6 @@
 module Faraday
   class Request::Authorization < Faraday::Middleware
-    KEY = "Authorization".freeze
+    KEY = "Authorization".freeze unless defined? KEY
 
     # Public
     def self.header(type, token)
@@ -30,8 +30,8 @@ module Faraday
 
     # Public
     def call(env)
-      unless env[:request_headers][KEY]
-        env[:request_headers][KEY] = @header_value
+      unless env.request_headers[KEY]
+        env.request_headers[KEY] = @header_value
       end
       @app.call(env)
     end

data/lib/faraday/request/basic_authentication.rb

@@ -1,7 +1,7 @@
 require 'base64'
 
 module Faraday
-  class Request::BasicAuthentication < Request::Authorization
+  class Request::BasicAuthentication < Request.load_middleware(:authorization)
     # Public
     def self.header(login, pass)
       value = Base64.encode64([login, pass].join(':'))

data/lib/faraday/request/instrumentation.rb

@@ -0,0 +1,38 @@
+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
+    end
+
+    def call(env)
+      @instrumenter.instrument(@name, env) do
+        @app.call(env)
+      end
+    end
+  end
+end
+
+

data/lib/faraday/request/multipart.rb

@@ -1,22 +1,23 @@
+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
@@ -32,14 +33,14 @@ module Faraday
     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

@@ -1,23 +1,87 @@
 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 an a retry interval.
+  #
+  # Examples
+  #
+  #   Faraday.new do |conn|
+  #     conn.request :retry, max: 2, interval: 0.05,
+  #                          exceptions: [CustomException, 'Timeout::Error']
+  #     conn.adapter ...
+  #   end
   class Request::Retry < Faraday::Middleware
-    def initialize(app, retries = 2)
-      @retries = retries
+    class Options < Faraday::Options.new(:max, :interval, :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 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).
+    # 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 call(env)
-      retries = @retries
-      request_body = env[:body]
+      retries = @options.max
       begin
-        env[:body] = request_body # after failure env[:body] is set to the response body
         @app.call(env)
-      rescue StandardError, Timeout::Error
+      rescue @errmatch
         if retries > 0
           retries -= 1
+          sleep @options.interval if @options.interval > 0
           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 then 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

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

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,25 +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)
       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