faraday 0.6.0 → 0.9.0

data/lib/faraday.rb

@@ -1,88 +1,268 @@
+require 'thread'
+require 'cgi'
+require 'set'
+require 'forwardable'
+
+# Public: This is the main namespace for Faraday.  You can either use it to
+# create Faraday::Connection objects, or access it directly.
+#
+# Examples
+#
+#   Faraday.get "http://faraday.com"
+#
+#   conn = Faraday.new "http://faraday.com"
+#   conn.get '/'
+#
 module Faraday
-  VERSION = "0.6.0"
+  VERSION = "0.9.0"
 
   class << self
-    attr_accessor :default_adapter
-    attr_writer   :default_connection
+    # 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
+
+    # Public: Gets or sets the path that the Faraday libs are loaded from.
+    attr_accessor :lib_path
+
+    # Public: Gets or sets the Symbol key identifying a default Adapter to use
+    # for the default Faraday::Connection.
+    attr_reader :default_adapter
+
+    # Public: Sets the default Faraday::Connection for simple scripts that
+    # access the Faraday constant directly.
+    #
+    #     Faraday.get "https://faraday.com"
+    attr_writer :default_connection
 
-    def new(url = nil, options = {})
+    # Public: Sets the default options used when calling Faraday#new.
+    attr_writer :default_connection_options
+
+    # 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'
+    #
+    #   # 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.dup
       Faraday::Connection.new(url, options, &block)
     end
 
+    # Internal: Requires internal Faraday libraries.
+    #
+    # *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
+
+    # Public: Updates default adapter while resetting
+    # #default_connection.
+    #
+    # Returns the new default_adapter.
+    def default_adapter=(adapter)
+      @default_connection = nil
+      @default_adapter = adapter
+    end
+
+    alias require_lib require_libs
+
   private
+    # Internal: Proxies method calls on the Faraday constant to
+    # #default_connection.
     def method_missing(name, *args, &block)
       default_connection.send(name, *args, &block)
     end
   end
 
+  self.root_path = File.expand_path "..", __FILE__
+  self.lib_path = File.expand_path "../faraday", __FILE__
   self.default_adapter = :net_http
 
+  # 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
   end
 
-  module AutoloadHelper
-    def register_lookup_modules(mods)
-      (@lookup_module_index ||= {}).update(mods)
+  # Gets the default connection options used when calling Faraday#new.
+  #
+  # Returns a Faraday::ConnectionOptions.
+  def self.default_connection_options
+    @default_connection_options ||= ConnectionOptions.new
+  end
+
+  if (!defined?(RUBY_ENGINE) || "ruby" == RUBY_ENGINE) && RUBY_VERSION < '1.9'
+    begin
+      require 'system_timer'
+      Timer = SystemTimer
+    rescue LoadError
+      warn "Faraday: you may want to install system_timer for reliable timeouts"
+    end
+  end
+
+  unless const_defined? :Timer
+    require 'timeout'
+    Timer = Timeout
+  end
+
+  # 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
 
-    def lookup_module(key)
-      return if !@lookup_module_index
-      const_get @lookup_module_index[key] || key
+    # 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 autoload_all(prefix, options)
-      options.each do |const_name, path|
-        autoload const_name, File.join(prefix, path)
+    def middleware_mutex(&block)
+      @middleware_mutex ||= begin
+        require 'monitor'
+        Monitor.new
       end
+      @middleware_mutex.synchronize(&block)
     end
 
-    # Loads each autoloaded constant.  If thread safety is a concern, wrap
-    # this in a Mutex.
-    def load_autoloaded_constants
-      constants.each do |const|
-        const_get(const) if autoload?(const)
+    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 all_loaded_constants
-      constants.map { |c| const_get(c) }.
-        select { |a| a.respond_to?(:loaded?) && a.loaded? }
+  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
 
-  extend AutoloadHelper
+  require_libs "utils", "options", "connection", "rack_builder", "parameters",
+    "middleware", "adapter", "request", "response", "upload_io", "error"
 
-  autoload_all 'faraday',
-    :Middleware      => 'middleware',
-    :Builder         => 'builder',
-    :Request         => 'request',
-    :Response        => 'response',
-    :CompositeReadIO => 'upload_io',
-    :UploadIO        => 'upload_io',
-    :Parts           => 'upload_io'
+  if !ENV["FARADAY_NO_AUTOLOAD"]
+    require_lib 'autoload'
+  end
 end
 
-require 'faraday/utils'
-require 'faraday/connection'
-require 'faraday/adapter'
-require 'faraday/error'
-
-# not pulling in active-support JUST for this method.
+# not pulling in active-support JUST for this method.  And I love this method.
 class Object
-  # Yields <code>x</code> to the block, and then returns <code>x</code>.
   # The primary purpose of this method is to "tap into" a method chain,
   # in order to perform operations on intermediate results within the chain.
   #
+  # Examples
+  #
   #   (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
   #     tap    { |x| puts "array: #{x.inspect}" }.
   #     select { |x| x%2 == 0 }.
   #     tap    { |x| puts "evens: #{x.inspect}" }.
   #     map    { |x| x*x }.
   #     tap    { |x| puts "squares: #{x.inspect}" }
+  #
+  # Yields self.
+  # Returns self.
   def tap
-    yield self
+    yield(self)
     self
   end unless Object.respond_to?(:tap)
 end

data/script/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Usage: script/console
+# Starts an IRB console with this library loaded.
+
+gemspec="$(ls *.gemspec | head -1)"
+
+exec bundle exec irb -r "${gemspec%.*}"

data/script/generate_certs

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# Usage: generate_certs
+# Generate test certs for testing Faraday with SSL
+
+require 'openssl'
+require 'fileutils'
+
+$shell = ARGV.include? '-s'
+
+# Adapted from WEBrick::Utils. Skips cert extensions so it
+# can be used as a CA bundle
+def create_self_signed_cert(bits, cn, comment)
+  rsa = OpenSSL::PKey::RSA.new(bits)
+  cert = OpenSSL::X509::Certificate.new
+  cert.version = 2
+  cert.serial = 1
+  name = OpenSSL::X509::Name.new(cn)
+  cert.subject = name
+  cert.issuer = name
+  cert.not_before = Time.now
+  cert.not_after = Time.now + (365*24*60*60)
+  cert.public_key = rsa.public_key
+  cert.sign(rsa, OpenSSL::Digest::SHA1.new)
+  return [cert, rsa]
+end
+
+def write(file, contents, env_var)
+  FileUtils.mkdir_p(File.dirname(file))
+  File.open(file, 'w') {|f| f.puts(contents) }
+  puts %(export #{env_var}="#{file}") if $shell
+end
+
+
+# One cert / CA for ease of testing when ignoring verification
+cert, key = create_self_signed_cert(1024, [['CN', 'localhost']], 'Faraday Test CA')
+write 'tmp/faraday-cert.key', key,  'SSL_KEY'
+write 'tmp/faraday-cert.crt', cert, 'SSL_FILE'
+
+# And a second CA to prove that verification can fail
+cert, key = create_self_signed_cert(1024, [['CN', 'real-ca.com']], 'A different CA')
+write 'tmp/faraday-different-ca-cert.key', key,  'SSL_KEY_ALT'
+write 'tmp/faraday-different-ca-cert.crt', cert, 'SSL_FILE_ALT'

data/script/package

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Usage: script/gem
+# Updates the gemspec and builds a new gem in the pkg directory.
+
+mkdir -p pkg
+gem build *.gemspec
+mv *.gem pkg

data/script/proxy-server

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# Usage: script/proxy-server [-p PORT] [-u USER:PASSWORD]
+require 'webrick'
+require 'webrick/httpproxy'
+
+port = 4001
+
+if found = ARGV.index('-p')
+  port = ARGV[found + 1].to_i
+end
+if found = ARGV.index('-u')
+  username, password = ARGV[found + 1].split(':', 2)
+end
+
+match_credentials = lambda { |credentials|
+  got_username, got_password = credentials.to_s.unpack("m*")[0].split(":", 2)
+  got_username == username && got_password == password
+}
+
+log_io = $stdout
+log_io.sync = true
+
+webrick_opts = {
+  :Port => port, :Logger => WEBrick::Log::new(log_io),
+  :AccessLog => [[log_io, "[%{X-Faraday-Adapter}i] %m  %U  ->  %s %b"]],
+  :ProxyAuthProc => lambda { |req, res|
+    if username
+      type, credentials = req.header['proxy-authorization'].first.to_s.split(/\s+/, 2)
+      unless "Basic" == type && match_credentials.call(credentials)
+        res['proxy-authenticate'] = %{Basic realm="testing"}
+        raise WEBrick::HTTPStatus::ProxyAuthenticationRequired
+      end
+    end
+  }
+}
+
+proxy = WEBrick::HTTPProxyServer.new(webrick_opts)
+
+trap(:TERM) { proxy.shutdown }
+trap(:INT) { proxy.shutdown }
+
+proxy.start

data/script/release

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Usage: script/release
+# Build the package, tag a commit, push it to origin, and then release the
+# package publicly.
+
+set -e
+
+version="$(script/package | grep Version: | awk '{print $2}')"
+[ -n "$version" ] || exit 1
+
+git commit --allow-empty -a -m "Release $version"
+git tag "v$version"
+git push origin
+git push origin "v$version"
+git push legacy
+git push legacy "v$version"
+gem push pkg/*-${version}.gem

data/script/server

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+old_verbose, $VERBOSE = $VERBOSE, nil
+begin
+  require File.expand_path('../../test/live_server', __FILE__)
+ensure
+  $VERBOSE = old_verbose
+end
+require 'webrick'
+
+port = 4000
+if found = ARGV.index('-p')
+  port = ARGV[found + 1].to_i
+end
+
+log_io = $stdout
+log_io.sync = true
+
+webrick_opts = {
+  :Port => port, :Logger => WEBrick::Log::new(log_io),
+  :AccessLog => [[log_io, "[%{X-Faraday-Adapter}i] %m  %U  ->  %s %b"]]
+}
+
+if ENV['SSL_KEY']
+  require 'openssl'
+  require 'webrick/https'
+  webrick_opts.update \
+    :SSLEnable       => true,
+    :SSLPrivateKey   => OpenSSL::PKey::RSA.new(File.read(ENV['SSL_KEY'])),
+    :SSLCertificate  => OpenSSL::X509::Certificate.new(File.read(ENV['SSL_FILE'])),
+    :SSLVerifyClient => OpenSSL::SSL::VERIFY_NONE
+end
+
+Rack::Handler::WEBrick.run(Faraday::LiveServer, webrick_opts) do |server|
+  trap(:INT)  { server.stop }
+  trap(:TERM) { server.stop }
+end

data/script/test

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# Usage: script/test [file] [adapter]... -- [test/unit options]
+# Runs the test suite against a local server spawned automatically in a
+# thread. After tests are done, the server is shut down.
+#
+# If filename arguments are given, only those files are run. If arguments given
+# are not filenames, they are taken as words that filter the list of files to run.
+#
+# Examples:
+#
+#   $ script/test
+#   $ script/test test/env_test.rb
+#   $ script/test excon typhoeus
+#
+#   # Run only tests matching /ssl/ for the net_http adapter, with SSL enabled.
+#   $ SSL=yes script/test net_http -- -n /ssl/
+#
+#   # Run against multiple rbenv versions
+#   $ RBENV_VERSIONS="1.9.3-p194 ree-1.8.7-2012.02" script/test
+set -e
+
+if [[ "$RUBYOPT" != *"bundler/setup"* ]]; then
+  export RUBYOPT="-rbundler/setup $RUBYOPT"
+fi
+
+port=3999
+proxy_port=3998
+scheme=http
+
+if [ "$SSL" = "yes" ]; then
+  scheme=https
+  if [ -z "$SSL_KEY" ] || [ -z "$SSL_FILE" ]; then
+    eval "$(script/generate_certs -s)"
+  fi
+fi
+
+find_test_files() {
+  find "$1" -name '*_test.rb'
+}
+
+filter_matching() {
+  pattern="$1"
+  shift
+  for line in "$@"; do
+    [[ $line == *"$pattern"* ]] && echo "$line"
+  done
+}
+
+start_server() {
+  mkdir -p log
+  script/server -p $port >log/test.log 2>&1 &
+  echo $!
+}
+
+start_proxy() {
+  mkdir -p log
+  script/proxy-server -p $proxy_port -u "faraday@test.local:there is cake" >log/proxy.log 2>&1 &
+  echo $!
+}
+
+server_started() {
+  lsof -i :${1?} >/dev/null
+}
+
+timestamp() {
+  date +%s
+}
+
+wait_for_server() {
+  timeout=$(( `timestamp` + $1 ))
+  while true; do
+    if server_started "$2"; then
+      break
+    elif [ `timestamp` -gt "$timeout" ]; then
+      echo "timed out after $1 seconds" >&2
+      return 1
+    fi
+  done
+}
+
+filtered=
+IFS=$'\n' test_files=($(find_test_files "test"))
+declare -a explicit_files
+
+# Process filter arguments:
+# - test filenames as taken as-is
+# - other words are taken as pattern to match the list of known files against
+# - arguments after "--" are forwarded to the ruby process
+while [ $# -gt 0 ]; do
+  arg="$1"
+  shift
+  if [ "$arg" = "--" ]; then
+    break
+  elif [ -f "$arg" ]; then
+    filtered=true
+    explicit_files[${#explicit_files[@]}+1]="$arg"
+  else
+    filtered=true
+    IFS=$'\n' explicit_files=(
+      ${explicit_files[@]}
+      $(filter_matching "$arg" "${test_files[@]}" || true)
+    )
+  fi
+done
+
+# If there were filter args, replace test files list with the results
+if [ -n "$filtered" ]; then
+  if [ ${#explicit_files[@]} -eq 0 ]; then
+    echo "Error: no test files match" >&2
+    exit 1
+  else
+    test_files=(${explicit_files[@]})
+    echo running "${test_files[@]}"
+  fi
+fi
+
+# If there are any adapter tests, spin up the HTTP server
+if [ -n "$(filter_matching "adapters" "${test_files[@]}")" ]; then
+  if server_started $port; then
+    echo "aborted: another instance of server running on $port" >&2
+    exit 1
+  fi
+  server_pid=$(start_server)
+  proxy_pid=$(start_proxy)
+  wait_for_server 30 $port || {
+    cat log/test.log
+    kill "$server_pid"
+    kill "$proxy_pid"
+    exit 1
+  }
+  wait_for_server 5 $proxy_port
+  cleanup() {
+    if [ $? -ne 0 ] && [ -n "$TRAVIS" ]; then
+      cat log/test.log
+    fi
+    kill "$server_pid"
+    kill "$proxy_pid"
+  }
+  trap cleanup INT EXIT
+  export LIVE="${scheme}://localhost:${port}"
+  export LIVE_PROXY="http://faraday%40test.local:there%20is%20cake@localhost:${proxy_port}"
+fi
+
+warnings="${TMPDIR:-/tmp}/faraday-warnings.$$"
+
+run_test_files() {
+  # Save warnings on stderr to a separate file
+  RUBYOPT="$RUBYOPT -w" ruby -e 'while f=ARGV.shift and f!="--"; load f; end' "${test_files[@]}" -- "$@" \
+    2> >(tee >(grep 'warning:' >"$warnings") | grep -v 'warning:')
+}
+
+check_warnings() {
+  # Display Ruby warnings from this project's source files. Abort if any were found.
+  num="$(grep -F "$PWD" "$warnings" | grep -v "${PWD}/bundle" | sort | uniq -c | sort -rn | tee /dev/stderr | wc -l)"
+  rm -f "$warnings"
+  if [ "$num" -gt 0 ]; then
+    echo "FAILED: this test suite doesn't tolerate Ruby syntax warnings!" >&2
+    exit 1
+  fi
+}
+
+if [ -n "$RBENV_VERSIONS" ]; then
+  IFS=' ' versions=($RBENV_VERSIONS)
+  for version in "${versions[@]}"; do
+    echo "[${version}]"
+    RBENV_VERSION="$version" run_test_files "$@"
+  done
+else
+  run_test_files "$@"
+fi
+
+check_warnings

data/test/adapters/default_test.rb

@@ -0,0 +1,14 @@
+require File.expand_path('../integration', __FILE__)
+
+module Adapters
+  class DefaultTest < Faraday::TestCase
+
+    def adapter() :default end
+
+    Integration.apply(self, :NonParallel) do
+      # default stack is not configured with Multipart
+      undef :test_POST_sends_files
+    end
+
+  end
+end

data/test/adapters/em_http_test.rb

@@ -0,0 +1,20 @@
+require File.expand_path('../integration', __FILE__)
+
+module Adapters
+  class EMHttpTest < Faraday::TestCase
+
+    def adapter() :em_http end
+
+    Integration.apply(self, :Parallel) do
+      # https://github.com/eventmachine/eventmachine/pull/289
+      undef :test_timeout
+
+      def test_binds_local_socket
+        host = '1.2.3.4'
+        conn = create_connection :request => { :bind => { :host => host } }
+        assert_equal host, conn.options[:bind][:host]
+      end
+    end unless jruby? and ssl_mode?
+    # https://github.com/eventmachine/eventmachine/issues/180
+  end
+end

data/test/adapters/em_synchrony_test.rb

@@ -0,0 +1,20 @@
+require File.expand_path('../integration', __FILE__)
+
+module Adapters
+  class EMSynchronyTest < Faraday::TestCase
+
+    def adapter() :em_synchrony end
+
+    Integration.apply(self, :Parallel) do
+      # https://github.com/eventmachine/eventmachine/pull/289
+      undef :test_timeout
+
+      def test_binds_local_socket
+        host = '1.2.3.4'
+        conn = create_connection :request => { :bind => { :host => host } }
+        #put conn.get('/who-am-i').body
+        assert_equal host, conn.options[:bind][:host]
+      end
+    end unless RUBY_VERSION < '1.9' or jruby?
+  end
+end