faraday 0.9.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1c31dbb021fc6a43b4f0b102a9a3ccf52a72303a
-  data.tar.gz: 54da868027777adb5a21145bd6433b0154af2297
+SHA256:
+  metadata.gz: 010e4dd27187eb834e8a0c185cab419a1b69c6e3f8a5728f6681109b7848091d
+  data.tar.gz: ccd678f8acf84929c15a19b7a6ca1b22b2d634eabfae21c84c4a0f0ba97fb8b6
 SHA512:
-  metadata.gz: 22c1c286687ca596bd1d6b7d9a6a3749731f6d8962a5bbbe7e1e39cf22e364b92010ae44446cf1804ba10567a2e6409cc2be537375d9f47ace9bca909196dcd3
-  data.tar.gz: 7e8116cdeea918b8e7de661ec6d49d839960e26f136903e53db62e8cc353f89b3ac053d5efe6401995129418ae4dfce8fda9c8a471093223dca08002615d10e1
+  metadata.gz: 150271b18c60bf5b55cc7e74f39fb01d6c83eecc39119d425fe8d399829ba728183900a5a948dbb874f432fc95996b88c367e87b5274b45addbd15d6175d7bc0
+  data.tar.gz: 3f4ef0b5d787aeffef29d79af04297a62a6b1ae77f034858b7d68ac4bdcfc00734c976cb8dff8b76b0af007590c6f4a5376797c14d3798cc13193aed96689d0c

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2013 Rick Olson, Zack Hobson
+Copyright (c) 2009-2019 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,200 +1,32 @@
-# Faraday
+# ![Faraday](./docs/assets/img/repo-card-slim.png)
 
-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.
-
-Faraday supports these adapters:
-
-* Net::HTTP
-* [Excon][]
-* [Typhoeus][]
-* [Patron][]
-* [EventMachine][]
-* [HTTPClient][]
-
-It also includes a Rack adapter for hitting loaded Rack applications through
-Rack::Test, and a Test adapter for stubbing requests by hand.
-
-## Usage
-
-```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
-
-## 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
-
-# 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
-```
-
-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)):
-
-```ruby
-response = Faraday.get 'http://sushi.com/nigiri/sake.json'
-```
-
-## 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
-
-  conn.adapter :net_http
-end
-```
+[![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)
+[![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-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
-```
-
-## 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
-```
+Faraday is an HTTP client library 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.
 
-## TODO
+## Getting Started
 
-* support streaming requests/responses
-* better stubbing API
+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.
 
 ## Supported Ruby versions
 
-This library aims to support and is [tested against][travis] the following Ruby
+This library aims to support and is [tested against][circle_ci] the following Ruby
 implementations:
 
-* MRI 1.8.7
-* MRI 1.9.2
-* MRI 1.9.3
-* MRI 2.0.0
-* MRI 2.1.0
-* [JRuby][]
-* [Rubinius][]
+* Ruby 2.3+
 
 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, however support will only be provided for the versions listed
+implementations and versions, however support will only be provided for the versions listed
 above.
 
 If you would like this library to support another Ruby version, you may
@@ -204,17 +36,20 @@ implementation, you will be responsible for providing patches in a timely
 fashion. If critical issues for a particular implementation exist at the time
 of a major release, support for that Ruby version may be dropped.
 
-## Copyright
+## Contribute
 
-Copyright (c) 2009-2013 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
-See [LICENSE][] for details.
+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]
 
-[travis]:    http://travis-ci.org/lostisland/faraday
-[excon]:     https://github.com/geemus/excon#readme
-[typhoeus]:  https://github.com/typhoeus/typhoeus#readme
-[patron]:    http://toland.github.com/patron/
-[eventmachine]: https://github.com/igrigorik/em-http-request#readme
-[httpclient]: https://github.com/nahi/httpclient
-[jruby]:     http://jruby.org/
-[rubinius]:  http://rubini.us/
-[license]:   LICENSE.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
+[jruby]:        http://jruby.org/
+[rubinius]:     http://rubini.us/
+[license]:      LICENSE.md

data/lib/faraday/adapter/em_http.rb

@@ -1,10 +1,15 @@
+# frozen_string_literal: true
+
 module Faraday
   class Adapter
-    # EventMachine adapter is useful for either asynchronous requests
-    # when in EM reactor loop or for making parallel requests in
+    # EventMachine adapter. This adapter is useful for either asynchronous
+    # requests when in an EM reactor loop, or for making parallel requests in
     # synchronous code.
     class EMHttp < Faraday::Adapter
+      # Options is a module containing helpers to convert the Faraday env object
+      # into options hashes for EMHTTP method calls.
       module Options
+        # @return [Hash]
         def connection_config(env)
           options = {}
           configure_proxy(options, env)
@@ -16,10 +21,10 @@ module Faraday
 
         def request_config(env)
           options = {
-            :body => read_body(env),
-            :head => env[:request_headers],
-            # :keepalive => true,
-            # :file => 'path/to/file', # stream data off disk
+            body: read_body(env),
+            head: env[:request_headers]
+            # keepalive: true,
+            # file: 'path/to/file', # stream data off disk
           }
           configure_compression(options, env)
           options
@@ -30,44 +35,53 @@ module Faraday
           body.respond_to?(:read) ? body.read : body
         end
 
+        # Reads out proxy settings from env into options
         def configure_proxy(options, env)
-          if proxy = request_options(env)[:proxy]
-            options[:proxy] = {
-              :host => proxy[:uri].host,
-              :port => proxy[:uri].port,
-              :authorization => [proxy[:user], proxy[:password]]
-            }
-          end
+          proxy = request_options(env)[:proxy]
+          return unless proxy
+
+          options[:proxy] = {
+            host: proxy[:uri].host,
+            port: proxy[:uri].port,
+            authorization: [proxy[:user], proxy[:password]]
+          }
         end
 
+        # Reads out host and port settings from env into options
         def configure_socket(options, env)
-          if bind = request_options(env)[:bind]
-            options[:bind] = {
-              :host => bind[:host],
-              :port => bind[:port]
-            }
-          end
+          bind = request_options(env)[:bind]
+          return unless bind
+
+          options[:bind] = {
+            host: bind[:host],
+            port: bind[:port]
+          }
         end
 
+        # Reads out SSL certificate settings from env into options
         def configure_ssl(options, env)
-          if env[:url].scheme == 'https' && env[:ssl]
-            options[:ssl] = {
-              :cert_chain_file => env[:ssl][:ca_file],
-              :verify_peer => env[:ssl].fetch(:verify, true)
-            }
-          end
+          return unless env[:url].scheme == 'https' && env[:ssl]
+
+          options[:ssl] = {
+            cert_chain_file: env[:ssl][:ca_file],
+            verify_peer: env[:ssl].fetch(:verify, true)
+          }
         end
 
+        # Reads out timeout settings from env into options
         def configure_timeout(options, env)
-          timeout, open_timeout = request_options(env).values_at(:timeout, :open_timeout)
+          timeout, open_timeout = request_options(env)
+                                  .values_at(:timeout, :open_timeout)
           options[:connect_timeout] = options[:inactivity_timeout] = timeout
           options[:connect_timeout] = open_timeout if open_timeout
         end
 
+        # Reads out compression header settings from env into options
         def configure_compression(options, env)
-          if env[:method] == :get and not options[:head].key? 'accept-encoding'
-            options[:head]['accept-encoding'] = 'gzip, compressed'
-          end
+          return unless (env[:method] == :get) &&
+                        !options[:head].key?('accept-encoding')
+
+          options[:head]['accept-encoding'] = 'gzip, compressed'
         end
 
         def request_options(env)
@@ -81,7 +95,8 @@ module Faraday
 
       self.supports_parallel = true
 
-      def self.setup_parallel_manager(options = nil)
+      # @return [Manager]
+      def self.setup_parallel_manager(_options = nil)
         Manager.new
       end
 
@@ -94,89 +109,113 @@ module Faraday
       def perform_request(env)
         if parallel?(env)
           manager = env[:parallel_manager]
-          manager.add {
-            perform_single_request(env).
-              callback { env[:response].finish(env) }
-          }
-        else
-          unless EventMachine.reactor_running?
-            error = nil
-            # start EM, block until request is completed
-            EventMachine.run do
-              perform_single_request(env).
-                callback { EventMachine.stop }.
-                errback { |client|
-                  error = error_message(client)
-                  EventMachine.stop
-                }
+          manager.add do
+            perform_single_request(env)
+              .callback { env[:response].finish(env) }
+          end
+        elsif EventMachine.reactor_running?
+          # EM is running: instruct upstream that this is an async request
+          env[:parallel_manager] = true
+          perform_single_request(env)
+            .callback { env[:response].finish(env) }
+            .errback do
+              # TODO: no way to communicate the error in async mode
+              raise NotImplementedError
             end
-            raise_error(error) if error
-          else
-            # EM is running: instruct upstream that this is an async request
-            env[:parallel_manager] = true
-            perform_single_request(env).
-              callback { env[:response].finish(env) }.
-              errback {
-                # TODO: no way to communicate the error in async mode
-                raise NotImplementedError
-              }
+        else
+          error = nil
+          # start EM, block until request is completed
+          EventMachine.run do
+            perform_single_request(env)
+              .callback { EventMachine.stop }
+              .errback do |client|
+                error = error_message(client)
+                EventMachine.stop
+              end
           end
+          raise_error(error) if error
         end
-      rescue EventMachine::Connectify::CONNECTError => err
-        if err.message.include?("Proxy Authentication Required")
-          raise Error::ConnectionFailed, %{407 "Proxy Authentication Required "}
-        else
-          raise Error::ConnectionFailed, err
+      rescue EventMachine::Connectify::CONNECTError => e
+        if e.message.include?('Proxy Authentication Required')
+          raise Faraday::ConnectionFailed,
+                %(407 "Proxy Authentication Required ")
         end
-      rescue => err
-        if defined?(OpenSSL) && OpenSSL::SSL::SSLError === err
-          raise Faraday::SSLError, err
-        else
-          raise
+
+        raise Faraday::ConnectionFailed, e
+      rescue StandardError => e
+        if defined?(OpenSSL) && e.is_a?(OpenSSL::SSL::SSLError)
+          raise Faraday::SSLError, e
         end
+
+        raise
       end
 
       # TODO: reuse the connection to support pipelining
       def perform_single_request(env)
-        req = EventMachine::HttpRequest.new(env[:url], connection_config(env))
-        req.setup_request(env[:method], request_config(env)).callback { |client|
-          save_response(env, client.response_header.status, client.response) do |resp_headers|
+        req = create_request(env)
+        req = req.setup_request(env[:method], request_config(env))
+        req.callback do |client|
+          if env[:request].stream_response?
+            warn "Streaming downloads for #{self.class.name} " \
+              'are not yet implemented.'
+            env[:request].on_data.call(
+              client.response,
+              client.response.bytesize
+            )
+          end
+          status = client.response_header.status
+          reason = client.response_header.http_reason
+          save_response(env, status, client.response, nil, reason) do |headers|
             client.response_header.each do |name, value|
-              resp_headers[name.to_sym] = value
+              headers[name.to_sym] = value
             end
           end
-        }
+        end
+      end
+
+      def create_request(env)
+        EventMachine::HttpRequest.new(
+          env[:url], connection_config(env).merge(@connection_options)
+        )
       end
 
       def error_message(client)
-        client.error or "request failed"
+        client.error || 'request failed'
       end
 
       def raise_error(msg)
-        errklass = Faraday::Error::ClientError
-        if msg == Errno::ETIMEDOUT
-          errklass = Faraday::Error::TimeoutError
-          msg = "request timed out"
+        error_class = Faraday::ClientError
+        if timeout_message?(msg)
+          error_class = Faraday::TimeoutError
+          msg = 'request timed out'
         elsif msg == Errno::ECONNREFUSED
-          errklass = Faraday::Error::ConnectionFailed
-          msg = "connection refused"
-        elsif msg == "connection closed by server"
-          errklass = Faraday::Error::ConnectionFailed
+          error_class = Faraday::ConnectionFailed
+          msg = 'connection refused'
+        elsif msg == 'connection closed by server'
+          error_class = Faraday::ConnectionFailed
         end
-        raise errklass, msg
+        raise error_class, msg
       end
 
+      def timeout_message?(msg)
+        msg == Errno::ETIMEDOUT ||
+          (msg.is_a?(String) && msg.include?('timeout error'))
+      end
+
+      # @return [Boolean]
       def parallel?(env)
         !!env[:parallel_manager]
       end
 
-      # The parallel manager is designed to start an EventMachine loop
+      # This parallel manager is designed to start an EventMachine loop
       # and block until all registered requests have been completed.
       class Manager
+        # @see reset
         def initialize
           reset
         end
 
+        # Re-initializes instance variables
         def reset
           @registered_procs = []
           @num_registered = 0
@@ -185,27 +224,30 @@ module Faraday
           @running = false
         end
 
-        def running?() @running end
+        # @return [Boolean]
+        def running?
+          @running
+        end
 
-        def add
+        def add(&block)
           if running?
             perform_request { yield }
           else
-            @registered_procs << Proc.new
+            @registered_procs << block
           end
           @num_registered += 1
         end
 
         def run
-          if @num_registered > 0
+          if @num_registered.positive?
             @running = true
             EventMachine.run do
               @registered_procs.each do |proc|
                 perform_request(&proc)
               end
             end
-            if @errors.size > 0
-              raise Faraday::Error::ClientError, @errors.first || "connection failed"
+            unless @errors.empty?
+              raise Faraday::ClientError, @errors.first || 'connection failed'
             end
           end
         ensure
@@ -214,24 +256,31 @@ module Faraday
 
         def perform_request
           client = yield
-          client.callback { @num_succeeded += 1; check_finished }
-          client.errback { @errors << client.error; check_finished }
+          client.callback do
+            @num_succeeded += 1
+            check_finished
+          end
+          client.errback do
+            @errors << client.error
+            check_finished
+          end
         end
 
         def check_finished
-          if @num_succeeded + @errors.size == @num_registered
-            EventMachine.stop
-          end
+          EventMachine.stop if @num_succeeded + @errors.size == @num_registered
         end
       end
     end
   end
 end
 
-begin
-  require 'openssl'
-rescue LoadError
-  warn "Warning: no such file to load -- openssl. Make sure it is installed if you want HTTPS support"
-else
-  require 'faraday/adapter/em_http_ssl_patch'
-end if Faraday::Adapter::EMHttp.loaded?
+if Faraday::Adapter::EMHttp.loaded?
+  begin
+    require 'openssl'
+  rescue LoadError
+    warn 'Warning: no such file to load -- openssl. ' \
+      'Make sure it is installed if you want HTTPS support'
+  else
+    require 'faraday/adapter/em_http_ssl_patch'
+  end
+end