faraday 0.16.2 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 382a791285d8cbe43d29471e437b2ad99e77d0428e53d2de3c0be7562d48b243
-  data.tar.gz: ef5893153bb55c9461389041611176056b26f65f18f288aa76cac795b660de5c
+  metadata.gz: 5fec2e4b9c0c8796f1b0dcb24807f456b121f13ae7f8de0f791d59e424ecb547
+  data.tar.gz: f2006014355f091959bda79594951e6fc7304e721433d203ee96ebe4c0058d63
 SHA512:
-  metadata.gz: 98f2ec6c8f92d4ff0493bd655d5d09ce1e09962efb6c9ba6f7eda174363f603f0e2ed068b4fb444ec119cd99b819df3e44f675419e24369c91a1db95a731223a
-  data.tar.gz: d5a8e2febb3d3ca040abad1147d70a41f26e2dc8dc0e72de707ab9b7caf400bc9308af2c6cb5aad92b267c9795daa28c42618e963a2e4cc061a7ece7ac713d10
+  metadata.gz: 53b8e3270ae2cb39b9608ca8fd860379210c87e1c3d9674db5b23b7fa123c44fe2a24e9c70618396525552875ac35f5372be0abd0aeffed7977151573e3cb833
+  data.tar.gz: 1de826ef4f4c6d448b64b808a5e93e9e0e92cd6f1799a14d9cdba0ef77c16114632fefd2c4bc80dcfb6015495610165035685f56454b9d4d3acb5fcd9b3f0d79

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2019 Rick Olson, Zack Hobson
+Copyright (c) 2009-2017 Rick Olson, Zack Hobson
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,32 +1,356 @@
-# ![Faraday](./docs/assets/img/repo-card-slim.png)
+# Faraday
 
 [![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
-[![CircleCI](https://circleci.com/gh/lostisland/faraday/tree/master.svg?style=svg)](https://circleci.com/gh/lostisland/faraday/tree/master)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/test_coverage)](https://codeclimate.com/github/lostisland/faraday/test_coverage)
-[![Maintainability](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/maintainability)](https://codeclimate.com/github/lostisland/faraday/maintainability)
+[![Build Status](https://travis-ci.org/lostisland/faraday.svg?branch=master)](https://travis-ci.org/lostisland/faraday)
+[![Coverage Status](https://coveralls.io/repos/github/lostisland/faraday/badge.svg?branch=master)](https://coveralls.io/github/lostisland/faraday?branch=master)
+[![Code Climate](https://codeclimate.com/github/lostisland/faraday/badges/gpa.svg)](https://codeclimate.com/github/lostisland/faraday)
 [![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 
-Faraday is an HTTP client library that provides a common interface over many
+Faraday is an HTTP client lib that provides a common interface over many
 adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
 processing the request/response cycle.
 
-## Getting Started
+Faraday supports these adapters out of the box:
 
-The best starting point is the [Faraday Website][website], with its introduction and explanation.
-Need more details? See the [Faraday API Documentation][apidoc] to see how it works internally.
+* [Net::HTTP][net_http] _(default)_
+* [Net::HTTP::Persistent][persistent]
+* [Excon][]
+* [Patron][]
+* [EventMachine][]
+* [HTTPClient][]
+
+Adapters are slowly being moved into their own gems, or bundled with HTTP clients:
+
+* [Typhoeus][]
+
+It also includes a Rack adapter for hitting loaded Rack applications through
+Rack::Test, and a Test adapter for stubbing requests by hand.
+
+## API documentation
+
+Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday).
+
+## Usage
+
+### Basic Use
+
+```ruby
+response = Faraday.get 'http://sushi.com/nigiri/sake.json'
+```
+A simple `get` request can be performed by using the syntax described above. This works if you don't need to set up anything; you can roll with just the default middleware
+stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)).
+
+A more flexible way to use Faraday is to start with a Connection object. If you want to keep the same defaults, you can use this syntax:
+
+```ruby
+conn = Faraday.new(:url => 'http://www.example.com')
+response = conn.get '/users'                 # GET http://www.example.com/users'
+```
+
+Connections can also take an options hash as a parameter or be configured by using a block. Checkout the section called [Advanced middleware usage](#advanced-middleware-usage) for more details about how to use this block for configurations.
+Since the default middleware stack uses url\_encoded middleware and default adapter, use them on building your own middleware stack.
+
+```ruby
+conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
+  faraday.request  :url_encoded             # form-encode POST params
+  faraday.response :logger                  # log requests to $stdout
+  faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
+end
+
+# Filter sensitive information from logs with a regex matcher
+
+conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
+  faraday.request  :url_encoded             # form-encode POST params
+  faraday.response :logger do | logger |
+    logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
+  end
+  faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
+end
+```
+
+Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways:
+
+```ruby
+## GET ##
+
+response = conn.get '/nigiri/sake.json'     # GET http://sushi.com/nigiri/sake.json
+response.body
+
+conn.get '/nigiri', { :name => 'Maguro' }   # GET http://sushi.com/nigiri?name=Maguro
+
+conn.get do |req|                           # GET http://sushi.com/search?page=2&limit=100
+  req.url '/search', :page => 2
+  req.params['limit'] = 100
+end
+
+## POST ##
+
+conn.post '/nigiri', { :name => 'Maguro' }  # POST "name=maguro" to http://sushi.com/nigiri
+```
+
+Some configuration options can be adjusted per request:
+
+```ruby
+# post payload as JSON instead of "www-form-urlencoded" encoding:
+conn.post do |req|
+  req.url '/nigiri'
+  req.headers['Content-Type'] = 'application/json'
+  req.body = '{ "name": "Unagi" }'
+end
+
+## Per-request options ##
+
+conn.get do |req|
+  req.url '/search'
+  req.options.timeout = 5           # open/read timeout in seconds
+  req.options.open_timeout = 2      # connection open timeout in seconds
+end
+```
+
+And you can inject arbitrary data into the request using the `context` option:
+
+```ruby
+# Anything you inject using context option will be available in the env on all middlewares
+
+conn.get do |req|
+  req.url '/search'
+  req.options.context = {
+      foo: 'foo',
+      bar: 'bar'
+  }
+end
+```
+
+### Changing how parameters are serialized
+
+Sometimes you need to send the same URL parameter multiple times with different
+values. This requires manually setting the parameter encoder and can be done on
+either per-connection or per-request basis.
+
+```ruby
+# per-connection setting
+conn = Faraday.new :request => { :params_encoder => Faraday::FlatParamsEncoder }
+
+conn.get do |req|
+  # per-request setting:
+  # req.options.params_encoder = my_encoder
+  req.params['roll'] = ['california', 'philadelphia']
+end
+# GET 'http://sushi.com?roll=california&roll=philadelphia'
+```
+
+The value of Faraday `params_encoder` can be any object that responds to:
+
+* `encode(hash) #=> String`
+* `decode(string) #=> Hash`
+
+The encoder will affect both how query strings are processed and how POST bodies
+get serialized. The default encoder is Faraday::NestedParamsEncoder.
+
+## Authentication
+
+Basic and Token authentication are handled by Faraday::Request::BasicAuthentication and Faraday::Request::TokenAuthentication respectively. These can be added as middleware manually or through the helper methods.
+
+```ruby
+Faraday.new(...) do |conn|
+  conn.basic_auth('username', 'password')
+end
+
+Faraday.new(...) do |conn|
+  conn.token_auth('authentication-token')
+end
+```
+
+## Proxy
+
+Faraday will try to automatically infer the proxy settings from your system using `URI#find_proxy`.
+This will retrieve them from environment variables such as http_proxy, ftp_proxy, no_proxy, etc.
+If for any reason you want to disable this behaviour, you can do so by setting the global varibale `ignore_env_proxy`:
+
+```ruby
+Faraday.ignore_env_proxy = true
+```
+
+You can also specify a custom proxy when initializing the connection
+
+```ruby
+Faraday.new('http://www.example.com', :proxy => 'http://proxy.com')
+```
+
+## Advanced middleware usage
+
+The order in which middleware is stacked is important. Like with Rack, the
+first middleware on the list wraps all others, while the last middleware is the
+innermost one, so that must be the adapter.
+
+```ruby
+Faraday.new(...) do |conn|
+  # POST/PUT params encoders:
+  conn.request :multipart
+  conn.request :url_encoded
+  
+  # add custom middleware
+  conn.use MyMiddleware
+
+  # Last middleware must be the adapter:
+  conn.adapter :net_http
+end
+```
+
+This request middleware setup affects POST/PUT requests in the following way:
+
+1. `Request::Multipart` checks for files in the payload, otherwise leaves
+  everything untouched;
+2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
+  already encoded or of another type
+
+Swapping middleware means giving the other priority. Specifying the
+"Content-Type" for the request is explicitly stating which middleware should
+process it.
+
+Examples:
+
+```ruby
+# uploading a file:
+payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
+
+# "Multipart" middleware detects files and encodes with "multipart/form-data":
+conn.put '/profile', payload
+```
+
+## Writing middleware
+
+Middleware are classes that implement a `call` instance method. They hook into
+the request/response cycle.
+
+```ruby
+def call(request_env)
+  # do something with the request
+  # request_env[:request_headers].merge!(...)
+
+  @app.call(request_env).on_complete do |response_env|
+    # do something with the response
+    # response_env[:response_headers].merge!(...)
+  end
+end
+```
+
+It's important to do all processing of the response only in the `on_complete`
+block. This enables middleware to work in parallel mode where requests are
+asynchronous.
+
+The `env` is a hash with symbol keys that contains info about the request and,
+later, response. Some keys are:
+
+```
+# request phase
+:method - :get, :post, ...
+:url    - URI for the current request; also contains GET parameters
+:body   - POST parameters for :post/:put requests
+:request_headers
+
+# response phase
+:status - HTTP response status code, such as 200
+:body   - the response body
+:response_headers
+```
+
+## Ad-hoc adapters customization
+
+Faraday is intended to be a generic interface between your code and the adapter. However, sometimes you need to access a feature specific to one of the adapters that is not covered in Faraday's interface.
+
+When that happens, you can pass a block when specifying the adapter to customize it. The block parameter will change based on the adapter you're using. See below for some examples.
+
+### NetHttp
+```ruby
+conn = Faraday.new(...) do |f|
+  f.adapter :net_http do |http| # yields Net::HTTP
+    http.idle_timeout = 100
+    http.verify_callback = lambda do | preverify_ok, cert_store |
+      # do something here...
+    end
+  end
+end
+```
+
+### NetHttpPersistent
+```ruby
+conn = Faraday.new(...) do |f|
+  f.adapter :net_http_persistent, pool_size: 5 do |http| # yields Net::HTTP::Persistent
+    http.idle_timeout = 100
+    http.retry_change_requests = true
+  end
+end
+```
+
+### Patron
+```ruby
+conn = Faraday.new(...) do |f|
+  f.adapter :patron do |session| # yields Patron::Session
+    session.max_redirects = 10
+  end
+end
+```
+
+### HTTPClient
+```ruby
+conn = Faraday.new(...) do |f|
+  f.adapter :httpclient do |client| # yields HTTPClient
+    client.keep_alive_timeout = 20
+    client.ssl_config.timeout = 25
+  end
+end
+```
+
+## Using Faraday for testing
+
+```ruby
+# It's possible to define stubbed request outside a test adapter block.
+stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+  stub.get('/tamago') { |env| [200, {}, 'egg'] }
+end
+
+# You can pass stubbed request to the test adapter or define them in a block
+# or a combination of the two.
+test = Faraday.new do |builder|
+  builder.adapter :test, stubs do |stub|
+    stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
+  end
+end
+
+# It's also possible to stub additional requests after the connection has
+# been initialized. This is useful for testing.
+stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
+
+resp = test.get '/tamago'
+resp.body # => 'egg'
+resp = test.get '/ebi'
+resp.body # => 'shrimp'
+resp = test.get '/uni'
+resp.body # => 'urchin'
+resp = test.get '/else' #=> raises "no such stub" error
+
+# If you like, you can treat your stubs as mocks by verifying that all of
+# the stubbed calls were made. NOTE that this feature is still fairly
+# experimental: It will not verify the order or count of any stub, only that
+# it was called once during the course of the test.
+stubs.verify_stubbed_calls
+```
 
 ## Supported Ruby versions
 
-This library aims to support and is [tested against][circle_ci] the following Ruby
+This library aims to support and is [tested against][travis] the following Ruby
 implementations:
 
-* Ruby 2.3+
+* Ruby 1.9.3+
+* [JRuby][] 1.7+
+* [Rubinius][] 2+
 
 If something doesn't work on one of these Ruby versions, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
-implementations and versions, however support will only be provided for the versions listed
+implementations, however support will only be provided for the versions listed
 above.
 
 If you would like this library to support another Ruby version, you may
@@ -40,16 +364,21 @@ of a major release, support for that Ruby version may be dropped.
 
 Do you want to contribute to Faraday?
 Open the issues page and check for the `help wanted` label!
-But before you start coding, please read our [Contributing Guide][contributing]
+But before you start coding, please read our [Contributing Guide](https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md)
 
 ## Copyright
-© 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
 
-[website]:      https://lostisland.github.io/faraday
-[faraday_team]: https://lostisland.github.io/faraday/team
-[contributing]: https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md
-[apidoc]:       http://www.rubydoc.info/gems/faraday
-[circle_ci]:    https://circleci.com/gh/lostisland/faraday
+Copyright (c) 2009-2017 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
+See [LICENSE][] for details.
+
+[net_http]:     http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
+[persistent]:   https://github.com/drbrain/net-http-persistent
+[travis]:       https://travis-ci.org/lostisland/faraday
+[excon]:        https://github.com/excon/excon#readme
+[patron]:       http://toland.github.io/patron/
+[eventmachine]: https://github.com/igrigorik/em-http-request#readme
+[httpclient]:   https://github.com/nahi/httpclient
+[typhoeus]:     https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
 [jruby]:        http://jruby.org/
 [rubinius]:     http://rubini.us/
 [license]:      LICENSE.md

data/lib/faraday.rb

@@ -1,153 +1,129 @@
-# frozen_string_literal: true
-
+require 'thread'
 require 'cgi'
 require 'set'
 require 'forwardable'
-require 'faraday/middleware_registry'
-require 'faraday/dependency_loader'
 
-# This is the main namespace for Faraday.
+# Public: This is the main namespace for Faraday.  You can either use it to
+# create Faraday::Connection objects, or access it directly.
 #
-# It provides methods to create {Connection} objects, and HTTP-related
-# methods to use directly.
+# Examples
 #
-# @example Helpful class methods for easy usage
 #   Faraday.get "http://faraday.com"
 #
-# @example Helpful class method `.new` to create {Connection} objects.
 #   conn = Faraday.new "http://faraday.com"
 #   conn.get '/'
 #
 module Faraday
-  VERSION = '0.16.2'
-  METHODS_WITH_QUERY = %w[get head delete connect trace].freeze
-  METHODS_WITH_BODY = %w[post put patch].freeze
+  VERSION = "0.17.0"
 
   class << self
-    # The root path that Faraday is being loaded from.
-    #
-    # This is the root from where the libraries are auto-loaded.
-    #
-    # @return [String]
+    # Public: Gets or sets the root path that Faraday is being loaded from.
+    # This is the root from where the libraries are auto-loaded from.
     attr_accessor :root_path
 
-    # Gets or sets the path that the Faraday libs are loaded from.
-    # @return [String]
+    # Public: Gets or sets the path that the Faraday libs are loaded from.
     attr_accessor :lib_path
 
-    # @overload default_adapter
-    #   Gets the Symbol key identifying a default Adapter to use
-    #   for the default {Faraday::Connection}. Defaults to `:net_http`.
-    #   @return [Symbol] the default adapter
-    # @overload default_adapter=(adapter)
-    #   Updates default adapter while resetting {.default_connection}.
-    #   @return [Symbol] the new default_adapter.
+    # Public: Gets or sets the Symbol key identifying a default Adapter to use
+    # for the default Faraday::Connection.
     attr_reader :default_adapter
 
-    # Documented below, see default_connection
+    # Public: Sets the default Faraday::Connection for simple scripts that
+    # access the Faraday constant directly.
+    #
+    #     Faraday.get "https://faraday.com"
     attr_writer :default_connection
 
-    # Tells Faraday to ignore the environment proxy (http_proxy).
-    # Defaults to `false`.
-    # @return [Boolean]
+    # Public: Tells faraday to ignore the environment proxy (http_proxy).
     attr_accessor :ignore_env_proxy
 
-    # Initializes a new {Connection}.
-    #
-    # @param url [String,Hash] The optional String base URL to use as a prefix
-    #           for all requests.  Can also be the options Hash. Any of these
-    #           values will be set on every request made, unless overridden
-    #           for a specific request.
-    # @param options [Hash]
-    # @option options [String] :url Base URL
-    # @option options [Hash] :params Hash of unencoded URI query params.
-    # @option options [Hash] :headers Hash of unencoded HTTP headers.
-    # @option options [Hash] :request Hash of request options.
-    # @option options [Hash] :ssl Hash of SSL options.
-    # @option options [Hash] :proxy Hash of Proxy options.
-    # @return [Faraday::Connection]
-    #
-    # @example With an URL argument
+    # Public: Initializes a new Faraday::Connection.
+    #
+    # url     - The optional String base URL to use as a prefix for all
+    #           requests.  Can also be the options Hash.
+    # options - The optional Hash used to configure this Faraday::Connection.
+    #           Any of these values will be set on every request made, unless
+    #           overridden for a specific request.
+    #           :url     - String base URL.
+    #           :params  - Hash of URI query unencoded key/value pairs.
+    #           :headers - Hash of unencoded HTTP header key/value pairs.
+    #           :request - Hash of request options.
+    #           :ssl     - Hash of SSL options.
+    #           :proxy   - Hash of Proxy options.
+    #
+    # Examples
+    #
     #   Faraday.new 'http://faraday.com'
-    #   # => Faraday::Connection to http://faraday.com
-    #
-    # @example With an URL argument and an options hash
-    #   Faraday.new 'http://faraday.com', params: { page: 1 }
-    #   # => Faraday::Connection to http://faraday.com?page=1
-    #
-    # @example With everything in an options hash
-    #   Faraday.new url: 'http://faraday.com',
-    #               params: { page: 1 }
-    #   # => Faraday::Connection to http://faraday.com?page=1
-    def new(url = nil, options = {}, &block)
-      options = default_connection_options.merge(options)
+    #
+    #   # http://faraday.com?page=1
+    #   Faraday.new 'http://faraday.com', :params => {:page => 1}
+    #
+    #   # same
+    #
+    #   Faraday.new :url => 'http://faraday.com',
+    #     :params => {:page => 1}
+    #
+    # Returns a Faraday::Connection.
+    def new(url = nil, options = nil)
+      block = block_given? ? Proc.new : nil
+      options = options ? default_connection_options.merge(options) : default_connection_options
       Faraday::Connection.new(url, options, &block)
     end
 
-    # @private
     # Internal: Requires internal Faraday libraries.
     #
-    # @param libs [Array] one or more relative String names to Faraday classes.
-    # @return [void]
+    # *libs - One or more relative String names to Faraday classes.
+    #
+    # Returns nothing.
     def require_libs(*libs)
       libs.each do |lib|
         require "#{lib_path}/#{lib}"
       end
     end
 
-    alias require_lib require_libs
-
-    # Documented elsewhere, see default_adapter reader
+    # Public: Updates default adapter while resetting
+    # #default_connection.
+    #
+    # Returns the new default_adapter.
     def default_adapter=(adapter)
       @default_connection = nil
       @default_adapter = adapter
     end
 
-    def respond_to_missing?(symbol, include_private = false)
+    alias require_lib require_libs
+
+    def respond_to?(symbol, include_private = false)
       default_connection.respond_to?(symbol, include_private) || super
     end
 
-    private
-
+  private
     # Internal: Proxies method calls on the Faraday constant to
-    # .default_connection.
+    # #default_connection.
     def method_missing(name, *args, &block)
-      if default_connection.respond_to?(name)
-        default_connection.send(name, *args, &block)
-      else
-        super
-      end
+      default_connection.send(name, *args, &block)
     end
   end
 
   self.ignore_env_proxy = false
-  self.root_path = File.expand_path __dir__
-  self.lib_path = File.expand_path 'faraday', __dir__
+  self.root_path = File.expand_path "..", __FILE__
+  self.lib_path = File.expand_path "../faraday", __FILE__
   self.default_adapter = :net_http
 
-  # @overload default_connection
-  #   Gets the default connection used for simple scripts.
-  #   @return [Faraday::Connection] a connection configured with
-  #   the default_adapter.
-  # @overload default_connection=(connection)
-  #   @param connection [Faraday::Connection]
-  #   Sets the default {Faraday::Connection} for simple scripts that
-  #   access the Faraday constant directly, such as
-  #   <code>Faraday.get "https://faraday.com"</code>.
+  # Gets the default connection used for simple scripts.
+  #
+  # Returns a Faraday::Connection, configured with the #default_adapter.
   def self.default_connection
     @default_connection ||= Connection.new(default_connection_options)
   end
 
-  # Gets the default connection options used when calling {Faraday#new}.
+  # Gets the default connection options used when calling Faraday#new.
   #
-  # @return [Faraday::ConnectionOptions]
+  # Returns a Faraday::ConnectionOptions.
   def self.default_connection_options
     @default_connection_options ||= ConnectionOptions.new
   end
 
-  # Sets the default options used when calling {Faraday#new}.
-  #
-  # @param options [Hash, Faraday::ConnectionOptions]
+  # Public: Sets the default options used when calling Faraday#new.
   def self.default_connection_options=(options)
     @default_connection = nil
     @default_connection_options = ConnectionOptions.from(options)
@@ -158,9 +134,115 @@ module Faraday
     Timer = Timeout
   end
 
-  require_libs 'utils', 'options', 'connection', 'rack_builder', 'parameters',
-               'middleware', 'adapter', 'request', 'response', 'error',
-               'file_part', 'param_part'
+  # Public: Adds the ability for other modules to register and lookup
+  # middleware classes.
+  module MiddlewareRegistry
+    # Public: Register middleware class(es) on the current module.
+    #
+    # mapping - A Hash mapping Symbol keys to classes. Classes can be expressed
+    #           as fully qualified constant, or a Proc that will be lazily
+    #           called to return the former.
+    #
+    # Examples
+    #
+    #   module Faraday
+    #     class Whatever
+    #       # Middleware looked up by :foo returns Faraday::Whatever::Foo.
+    #       register_middleware :foo => Foo
+    #
+    #       # Middleware looked up by :bar returns Faraday::Whatever.const_get(:Bar)
+    #       register_middleware :bar => :Bar
+    #
+    #       # Middleware looked up by :baz requires 'baz' and returns Faraday::Whatever.const_get(:Baz)
+    #       register_middleware :baz => [:Baz, 'baz']
+    #     end
+    #   end
+    #
+    # Returns nothing.
+    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
 
-  require_lib 'autoload' unless ENV['FARADAY_NO_AUTOLOAD']
+    # Public: Lookup middleware class with a registered Symbol shortcut.
+    #
+    # key - The Symbol key for the registered middleware.
+    #
+    # Examples
+    #
+    #   module Faraday
+    #     class Whatever
+    #       register_middleware :foo => Foo
+    #     end
+    #   end
+    #
+    #   Faraday::Whatever.lookup_middleware(:foo)
+    #   # => Faraday::Whatever::Foo
+    #
+    # Returns a middleware Class.
+    def lookup_middleware(key)
+      load_middleware(key) ||
+        raise(Faraday::Error.new("#{key.inspect} is not registered on #{self}"))
+    end
+
+    def middleware_mutex(&block)
+      @middleware_mutex ||= begin
+        require 'monitor'
+        Monitor.new
+      end
+      @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
+
+  def self.const_missing(name)
+    if name.to_sym == :Builder
+      warn "Faraday::Builder is now Faraday::RackBuilder."
+      const_set name, RackBuilder
+    else
+      super
+    end
+  end
+
+  require_libs "utils", "options", "connection", "rack_builder", "parameters",
+    "middleware", "adapter", "request", "response", "upload_io", "error"
+
+  if !ENV["FARADAY_NO_AUTOLOAD"]
+    require_lib 'autoload'
+  end
 end