sharpetronics/faraday
1
0
Fork 0
mirror of https://github.com/lostisland/faraday.git synced 2025-10-16 00:03:37 -04:00
Code Issues Projects Releases Wiki Activity

YARD annotations; Git ignore .yardoc/ (#788)

Browse Source
This commit is contained in:
Olle Jonsson 2018-04-17 16:08:09 +02:00 committed by Mattia
parent d9661c4567
commit 89b3365896
17 changed files with 241 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -20,3 +20,4 @@ vendor/bundle
## IDEs
.idea/
.yardoc/

4
lib/faraday/adapter.rb
View File

@ -1,5 +1,5 @@
module Faraday
# Public: This is a base class for all Faraday adapters. Adapters are
# Base class for all Faraday adapters. Adapters are
# responsible for fulfilling a Faraday request.
class Adapter < Middleware
CONTENT_LENGTH = 'Content-Length'.freeze
@ -16,7 +16,7 @@ module Faraday
:rack => [:Rack, 'rack'],
:httpclient => [:HTTPClient, 'httpclient']
# Public: This module marks an Adapter as supporting parallel requests.
# This module marks an Adapter as supporting parallel requests.
module Parallelism
attr_writer :supports_parallel
def supports_parallel?() @supports_parallel end

17
lib/faraday/adapter/em_http.rb
View File

@ -1,10 +1,11 @@
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
module Options
# @return [Hash]
def connection_config(env)
options = {}
configure_proxy(options, env)
@ -30,6 +31,7 @@ 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] = {
@ -40,6 +42,7 @@ module Faraday
end
end
# Reads out host and port settings from env into options
def configure_socket(options, env)
if bind = request_options(env)[:bind]
options[:bind] = {
@ -49,6 +52,7 @@ module Faraday
end
end
# Reads out SSL certificate settings from env into options
def configure_ssl(options, env)
if env[:url].scheme == 'https' && env[:ssl]
options[:ssl] = {
@ -58,12 +62,14 @@ module Faraday
end
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)
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'
@ -81,6 +87,7 @@ module Faraday
self.supports_parallel = true
# @return [Manager]
def self.setup_parallel_manager(options = nil)
Manager.new
end
@ -176,17 +183,20 @@ module Faraday
raise errklass, msg
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
@ -195,6 +205,7 @@ module Faraday
@running = false
end
# @return [Boolean]
def running?() @running end
def add

1
lib/faraday/adapter/em_http_ssl_patch.rb
View File

@ -1,6 +1,7 @@
require 'openssl'
require 'em-http'
# EventMachine patch to make SSL work.
module EmHttpSslPatch
def ssl_verify_peer(cert_string)
cert = nil

2
lib/faraday/adapter/em_synchrony.rb
View File

@ -2,6 +2,7 @@ require 'uri'
module Faraday
class Adapter
# EventMachine Synchrony adapter.
class EMSynchrony < Faraday::Adapter
include EMHttp::Options
@ -13,6 +14,7 @@ module Faraday
self.supports_parallel = true
# @return [ParallelManager]
def self.setup_parallel_manager(options = {})
ParallelManager.new
end

16
lib/faraday/adapter/em_synchrony/parallel_manager.rb
View File

@ -1,10 +1,14 @@
module Faraday
class Adapter
class EMSynchrony < Faraday::Adapter
# A parallel manager for EMSynchrony.
class ParallelManager
# Add requests to queue. The `request` argument should be a
# `EM::HttpRequest` object.
# Add requests to queue.
#
# @param request [EM::HttpRequest]
# @param method [Symbol, String] HTTP method
# @param args [Array] the rest of the positional arguments
def add(request, method, *args, &block)
queue << {
:request => request,
@ -60,7 +64,7 @@ module Faraday
multi.perform
end
end # ParallelManager
end # EMSynchrony
end # Adapter
end # Faraday
end
end
end
end

2
lib/faraday/adapter/excon.rb
View File

@ -1,5 +1,6 @@
module Faraday
class Adapter
# Excon adapter.
class Excon < Faraday::Adapter
dependency 'excon'
@ -70,6 +71,7 @@ module Faraday
raise Error::TimeoutError, err
end
# @return [Excon]
def create_connection(env, opts)
::Excon.new(env[:url].to_s, opts.merge(@connection_options))
end

11
lib/faraday/adapter/httpclient.rb
View File

@ -1,8 +1,10 @@
module Faraday
class Adapter
# HTTPClient adapter.
class HTTPClient < Faraday::Adapter
dependency 'httpclient'
# @return [HTTPClient]
def client
@client ||= ::HTTPClient.new
end
@ -64,11 +66,15 @@ module Faraday
end
end
# @param bind [Hash]
def configure_socket(bind)
client.socket_local.host = bind[:host]
client.socket_local.port = bind[:port]
end
# Configure proxy URI and any user credentials.
#
# @param proxy [Hash]
def configure_proxy(proxy)
client.proxy = proxy[:uri]
if proxy[:user] && proxy[:password]
@ -76,6 +82,7 @@ module Faraday
end
end
# @param ssl [Hash]
def configure_ssl(ssl)
ssl_config = client.ssl_config
ssl_config.verify_mode = ssl_verify_mode(ssl)
@ -88,6 +95,7 @@ module Faraday
ssl_config.verify_depth = ssl[:verify_depth] if ssl[:verify_depth]
end
# @param req [Hash]
def configure_timeouts(req)
if req[:timeout]
client.connect_timeout = req[:timeout]
@ -105,6 +113,8 @@ module Faraday
@config_block.call(client) if @config_block
end
# @param ssl [Hash]
# @return [OpenSSL::X509::Store]
def ssl_cert_store(ssl)
return ssl[:cert_store] if ssl[:cert_store]
# Memoize the cert store so that the same one is passed to
@ -118,6 +128,7 @@ module Faraday
end
end
# @param ssl [Hash]
def ssl_verify_mode(ssl)
ssl[:verify_mode] || begin
if ssl.fetch(:verify, true)

1
lib/faraday/adapter/net_http.rb
View File

@ -8,6 +8,7 @@ require 'zlib'
module Faraday
class Adapter
# Net::HTTP adapter.
class NetHttp < Faraday::Adapter
NET_HTTP_EXCEPTIONS = [
IOError,

1
lib/faraday/adapter/net_http_persistent.rb
View File

@ -1,5 +1,6 @@
module Faraday
class Adapter
# Net::HTTP::Persistent adapter.
class NetHttpPersistent < NetHttp
dependency 'net/http/persistent'

2
lib/faraday/adapter/patron.rb
View File

@ -1,5 +1,6 @@
module Faraday
class Adapter
# Patron adapter.
class Patron < Faraday::Adapter
dependency 'patron'
@ -69,6 +70,7 @@ module Faraday
end
end
# @return [Patron::Session]
def create_session
session = ::Patron::Session.new
@config_block.call(session) if @config_block

2
lib/faraday/adapter/rack.rb
View File

@ -2,7 +2,7 @@ module Faraday
class Adapter
# Sends requests to a Rack app.
#
# Examples
# @example
#
# class MyRackApp
# def call(env)

2
lib/faraday/adapter/typhoeus.rb
View File

@ -1,6 +1,6 @@
module Faraday
class Adapter
# This class is just a stub, the real adapter is in https://github.com/philsturgeon/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
# Typhoeus adapter. This class is just a stub, the real adapter is in https://github.com/philsturgeon/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
class Typhoeus < Faraday::Adapter
# Needs to define this method in order to support Typhoeus <= 1.3.0
def call; end

22
lib/faraday/autoload.rb
View File

@ -1,15 +1,17 @@
module Faraday
# Internal: Adds the ability for other modules to manage autoloadable
# Adds the ability for other modules to manage autoloadable
# constants.
#
# @api private
module AutoloadHelper
# Internal: Registers the constants to be auto loaded.
# Registers the constants to be auto loaded.
#
# prefix - The String require prefix. If the path is inside Faraday, then
# @param prefix [String] The require prefix. If the path is inside Faraday, then
# it will be prefixed with the root path of this loaded Faraday
# version.
# options - Hash of Symbol => String library names.
# @param options [{ Symbol => String }] library names.
#
# Examples.
# @example
#
# Faraday.autoload_all 'faraday/foo',
# :Bar => 'bar'
@ -18,7 +20,7 @@ module Faraday
# Faraday::Bar
#
#
# Returns nothing.
# @return [void]
def autoload_all(prefix, options)
if prefix =~ /^faraday(\/|$)/i
prefix = File.join(Faraday.root_path, prefix)
@ -28,20 +30,20 @@ module Faraday
end
end
# Internal: Loads each autoloaded constant. If thread safety is a concern,
# Loads each autoloaded constant. If thread safety is a concern,
# wrap this in a Mutex.
#
# Returns nothing.
# @return [void]
def load_autoloaded_constants
constants.each do |const|
const_get(const) if autoload?(const)
end
end
# Internal: Filters the module's contents with those that have been already
# Filters the module's contents with those that have been already
# autoloaded.
#
# Returns an Array of Class/Module objects.
# @return [Array<Class, Module>]
def all_loaded_constants
constants.map { |c| const_get(c) }.
select { |a| a.respond_to?(:loaded?) && a.loaded? }

264
lib/faraday/connection.rb
View File

@ -1,8 +1,8 @@
module Faraday
# Public: Connection objects manage the default properties and the middleware
# Connection objects manage the default properties and the middleware
# stack for fulfilling an HTTP request.
#
# Examples
# @example
#
# conn = Faraday::Connection.new 'http://sushi.com'
#
@ -14,49 +14,49 @@ module Faraday
# A Set of allowed HTTP verbs.
METHODS = Set.new [:get, :post, :put, :delete, :head, :patch, :options]
# Public: Returns a Hash of URI query unencoded key/value pairs.
# @return [Hash] URI query unencoded key/value pairs.
attr_reader :params
# Public: Returns a Hash of unencoded HTTP header key/value pairs.
# @return [Hash] unencoded HTTP header key/value pairs.
attr_reader :headers
# Public: Returns a URI with the prefix used for all requests from this
# Connection. This includes a default host name, scheme, port, and path.
# @return [String] a URI with the prefix used for all requests from this
# Connection. This includes a default host name, scheme, port, and path.
attr_reader :url_prefix
# Public: Returns the Faraday::Builder for this Connection.
# @return [Faraday::Builder] Builder for this Connection.
attr_reader :builder
# Public: Returns a Hash of the request options.
# @return [Hash] request options.
attr_reader :options
# Public: Returns a Hash of the SSL options.
# @return [Hash] SSL options.
attr_reader :ssl
# Public: Returns the parallel manager for this Connection.
# @return [Object] the parallel manager for this Connection.
attr_reader :parallel_manager
# Public: Sets the default parallel manager for this connection.
# Sets the default parallel manager for this connection.
attr_writer :default_parallel_manager
# Public: Gets the Hash proxy options.
# @return [Hash] proxy options.
attr_reader :proxy
# Public: Initializes a new Faraday::Connection.
# Initializes a new Faraday::Connection.
#
# url - URI or String base URL to use as a prefix for all
# @param url [URI, String] URI or String base URL to use as a prefix for all
# requests (optional).
# options - Hash or Faraday::ConnectionOptions.
# :url - URI or String base URL (default: "http:/").
# :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 - URI, String or Hash of HTTP proxy options
# (default: "http_proxy" environment variable).
# :uri - URI or String
# :user - String (optional)
# :password - String (optional)
# @param options [Hash, Faraday::ConnectionOptions]
# @option options [URI, String] :url URI or String base URL (default: "http:/").
# @option options [Hash<String => String>] :params URI query unencoded key/value pairs.
# @option options [Hash<String => String>] :headers Hash of unencoded HTTP header key/value pairs.
# @option options [Hash] :request Hash of request options.
# @option options [Hash] :ssl Hash of SSL options.
# @option options [Hash, URI, String] :proxy proxy options, either as a URL or as a Hash
# @option options [URI, String] :proxy[:uri]
# @option options [String] :proxy[:user]
# @option options [String] :proxy[:password]
# @yield [self] after all setup has been done
def initialize(url = nil, options = nil)
options = ConnectionOptions.from(options)
@ -91,12 +91,14 @@ module Faraday
@headers[:user_agent] ||= "Faraday v#{VERSION}"
end
# Public: Sets the Hash of URI query unencoded key/value pairs.
# Sets the Hash of URI query unencoded key/value pairs.
# @param hash [Hash]
def params=(hash)
@params.replace hash
end
# Public: Sets the Hash of unencoded HTTP header key/value pairs.
# Sets the Hash of unencoded HTTP header key/value pairs.
# @param hash [Hash]
def headers=(hash)
@headers.replace hash
end
@ -105,17 +107,17 @@ module Faraday
def_delegators :builder, :build, :use, :request, :response, :adapter, :app
# Public: Makes an HTTP request without a body.
# @!method get(url = nil, params = nil, headers = nil)
# Makes a GET HTTP request without a body.
# @!scope class
#
# url - The optional String base URL to use as a prefix for all
# @param url [String] The optional String base URL to use as a prefix for all
# requests. Can also be the options Hash.
# params - Hash of URI query unencoded key/value pairs.
# headers - Hash of unencoded HTTP header key/value pairs.
#
# Examples
# @param params [Hash] Hash of URI query unencoded key/value pairs.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# @example
# conn.get '/items', {:page => 1}, :accept => 'application/json'
# conn.head '/items/1'
#
# # ElasticSearch example sending a body with GET.
# conn.get '/twitter/tweet/_search' do |req|
@ -124,14 +126,40 @@ module Faraday
# req.body = JSON.generate(:query => {...})
# end
#
# Yields a Faraday::Request for further request customizations.
# Returns a Faraday::Response.
# @yield [Faraday::Request] for further request customizations
# @return [Faraday::Response]
# @!method head(url = nil, params = nil, headers = nil)
# Makes a HEAD HTTP request without a body.
# @!scope class
#
# Signature
# @param url [String] The optional String base URL to use as a prefix for all
# requests. Can also be the options Hash.
# @param params [Hash] Hash of URI query unencoded key/value pairs.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# <verb>(url = nil, params = nil, headers = nil)
# @example
# conn.head '/items/1'
#
# verb - An HTTP verb: get, head, or delete.
# @yield [Faraday::Request] for further request customizations
# @return [Faraday::Response]
# @!method delete(url = nil, params = nil, headers = nil)
# Makes a DELETE HTTP request without a body.
# @!scope class
#
# @param url [String] The optional String base URL to use as a prefix for all
# requests. Can also be the options Hash.
# @param params [Hash] Hash of URI query unencoded key/value pairs.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# @example
# conn.delete '/items/1'
#
# @yield [Faraday::Request] for further request customizations
# @return [Faraday::Response]
# @!visibility private
%w[get head delete].each do |method|
class_eval <<-RUBY, __FILE__, __LINE__ + 1
def #{method}(url = nil, params = nil, headers = nil)
@ -143,15 +171,16 @@ module Faraday
RUBY
end
# Public: Makes an HTTP request with a body.
# @!method post(url = nil, body = nil, headers = nil)
# Makes a POST HTTP request with a body.
# @!scope class
#
# url - The optional String base URL to use as a prefix for all
# @param url [String] The optional String base URL to use as a prefix for all
# requests. Can also be the options Hash.
# body - The String body for the request.
# headers - Hash of unencoded HTTP header key/value pairs.
#
# Examples
# @param body [String] body for the request.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# @example
# conn.post '/items', data, :content_type => 'application/json'
#
# # Simple ElasticSearch indexing sample.
@ -161,14 +190,33 @@ module Faraday
# req.body = JSON.generate(:user => 'kimchy', ...)
# end
#
# Yields a Faraday::Request for further request customizations.
# Returns a Faraday::Response.
# @yield [Faraday::Request] for further request customizations
# @return [Faraday::Response]
# @!method put(url = nil, body = nil, headers = nil)
# Makes a PUT HTTP request with a body.
# @!scope class
#
# Signature
# @param url [String] The optional String base URL to use as a prefix for all
# requests. Can also be the options Hash.
# @param body [String] body for the request.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# <verb>(url = nil, body = nil, headers = nil)
# @example
# # TODO: Make it a PUT example
# conn.post '/items', data, :content_type => 'application/json'
#
# verb - An HTTP verb: post, put, or patch.
# # Simple ElasticSearch indexing sample.
# conn.post '/twitter/tweet' do |req|
# req.headers[:content_type] = 'application/json'
# req.params[:routing] = 'kimchy'
# req.body = JSON.generate(:user => 'kimchy', ...)
# end
#
# @yield [Faraday::Request] for further request customizations
# @return [Faraday::Response]
# @!visibility private
%w[post put patch].each do |method|
class_eval <<-RUBY, __FILE__, __LINE__ + 1
def #{method}(url = nil, body = nil, headers = nil, &block)
@ -177,47 +225,47 @@ module Faraday
RUBY
end
# Public: Sets up the Authorization header with these credentials, encoded
# Sets up the Authorization header with these credentials, encoded
# with base64.
#
# login - The authentication login.
# pass - The authentication password.
# @param login [String] The authentication login.
# @param pass [String] The authentication password.
#
# Examples
# @example
#
# conn.basic_auth 'Aladdin', 'open sesame'
# conn.headers['Authorization']
# # => "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
#
# Returns nothing.
# @return [void]
def basic_auth(login, pass)
set_authorization_header(:basic_auth, login, pass)
end
# Public: Sets up the Authorization header with the given token.
# Sets up the Authorization header with the given token.
#
# token - The String token.
# options - Optional Hash of extra token options.
# @param token [String]
# @param options [Hash] extra token options.
#
# Examples
# @example
#
# conn.token_auth 'abcdef', :foo => 'bar'
# conn.headers['Authorization']
# # => "Token token=\"abcdef\",
# foo=\"bar\""
#
# Returns nothing.
# @return [void]
def token_auth(token, options = nil)
set_authorization_header(:token_auth, token, options)
end
# Public: Sets up a custom Authorization header.
# Sets up a custom Authorization header.
#
# type - The String authorization type.
# token - The String or Hash token. A String value is taken literally, and
# a Hash is encoded into comma separated key/value pairs.
# @param type [String] authorization type
# @param token [String, Hash] token. A String value is taken literally, and
# a Hash is encoded into comma-separated key/value pairs.
#
# Examples
# @example
#
# conn.authorization :Bearer, 'mF_9.B5f-4.1JqM'
# conn.headers['Authorization']
@ -228,16 +276,17 @@ module Faraday
# # => "Token token=\"abcdef\",
# foo=\"bar\""
#
# Returns nothing.
# @return [void]
def authorization(type, token)
set_authorization_header(:authorization, type, token)
end
# Internal: Check if the adapter is parallel-capable.
# Check if the adapter is parallel-capable.
#
# Yields otherwise or if no adapter is set yet.
# @yield if the adapter isn't parallel-capable, or if no adapter is set yet.
#
# Returns a parallel manager or nil if yielded.
# @return [Object, nil] a parallel manager or nil if yielded
# @api private
def default_parallel_manager
@default_parallel_manager ||= begin
adapter = @builder.adapter.klass if @builder.adapter
@ -250,19 +299,19 @@ module Faraday
end
end
# Public: Determine if this Faraday::Connection can make parallel requests.
# Determine if this Faraday::Connection can make parallel requests.
#
# Returns true or false.
# @return [Boolean]
def in_parallel?
!!@parallel_manager
end
# Public: Sets up the parallel manager to make a set of requests.
# Sets up the parallel manager to make a set of requests.
#
# manager - The parallel manager that this Connection's Adapter uses.
# @param manager [Object] The parallel manager that this Connection's Adapter uses.
#
# Yields a block to execute multiple requests.
# Returns nothing.
# @yield a block to execute multiple requests.
# @return [void]
def in_parallel(manager = nil)
@parallel_manager = manager || default_parallel_manager {
warn "Warning: `in_parallel` called but no parallel-capable adapter on Faraday stack"
@ -275,7 +324,9 @@ module Faraday
@parallel_manager = nil
end
# Public: Sets the Hash proxy options.
# Sets the Hash proxy options.
#
# @param new_value [Object]
def proxy=(new_value)
@manual_proxy = true
@proxy = new_value ? ProxyOptions.from(new_value) : nil
@ -284,13 +335,14 @@ module Faraday
def_delegators :url_prefix, :scheme, :scheme=, :host, :host=, :port, :port=
def_delegator :url_prefix, :path, :path_prefix
# Public: Parses the giving url with URI and stores the individual
# components in this connection. These components serve as defaults for
# Parses the given URL with URI and stores the individual
# components in this connection. These components serve as defaults for
# requests made by this connection.
#
# url - A String or URI.
# @param url [String, URI]
# @param encoder [Object]
#
# Examples
# @example
#
# conn = Faraday::Connection.new { ... }
# conn.url_prefix = "https://sushi.com/api"
@ -299,7 +351,7 @@ module Faraday
#
# conn.get("nigiri?page=2") # accesses https://sushi.com/api/nigiri
#
# Returns the parsed URI from the given input..
# @return [URI] the parsed URI from the given input
def url_prefix=(url, encoder = nil)
uri = @url_prefix = Utils.URI(url)
self.path_prefix = uri.path
@ -315,12 +367,12 @@ module Faraday
uri
end
# Public: Sets the path prefix and ensures that it always has a leading
# Sets the path prefix and ensures that it always has a leading
# slash.
#
# value - A String.
# @param value [String]
#
# Returns the new String path prefix.
# @return [String] the new path prefix
def path_prefix=(value)
url_prefix.path = if value
value = '/' + value unless value[0,1] == '/'
@ -328,9 +380,13 @@ module Faraday
end
end
# Public: Takes a relative url for a request and combines it with the defaults
# Takes a relative url for a request and combines it with the defaults
# set on the connection instance.
#
# @param url [String]
# @param extra_params [Hash]
#
# @example
# conn = Faraday::Connection.new { ... }
# conn.url_prefix = "https://sushi.com/api?token=abc"
# conn.scheme # => https
@ -351,12 +407,12 @@ module Faraday
# Builds and runs the Faraday::Request.
#
# method - The Symbol HTTP method.
# url - The String or URI to access.
# body - The request body that will eventually be converted to a string.
# headers - Hash of unencoded HTTP header key/value pairs.
# @param method [Symbol] HTTP method.
# @param url [String, URI] String or URI to access.
# @param body [Object] The request body that will eventually be converted to a string.
# @param headers [Hash] unencoded HTTP header key/value pairs.
#
# Returns a Faraday::Response.
# @return [Faraday::Response]
def run_request(method, url, body, headers)
if !METHODS.include?(method)
raise ArgumentError, "unknown http method: #{method}"
@ -378,7 +434,10 @@ module Faraday
# Creates and configures the request object.
#
# Returns the new Request.
# @param method [Symbol]
#
# @yield [Faraday::Request] if block given
# @return [Faraday::Request]
def build_request(method)
Request.create(method) do |req|
req.params = self.params.dup
@ -388,13 +447,13 @@ module Faraday
end
end
# Internal: Build an absolute URL based on url_prefix.
# Build an absolute URL based on url_prefix.
#
# url - A String or URI-like object
# params - A Faraday::Utils::ParamsHash to replace the query values
# @param url [String, URI]
# @param params [Faraday::Utils::ParamsHash] A Faraday::Utils::ParamsHash to replace the query values
# of the resulting url (default: nil).
#
# Returns the resulting URI instance.
# @return [URI]
def build_exclusive_url(url = nil, params = nil, params_encoder = nil)
url = nil if url.respond_to?(:empty?) and url.empty?
base = url_prefix
@ -408,9 +467,11 @@ module Faraday
uri
end
# Internal: Creates a duplicate of this Faraday::Connection.
# Creates a duplicate of this Faraday::Connection.
#
# Returns a Faraday::Connection.
# @api private
#
# @return [Faraday::Connection]
def dup
self.class.new(build_exclusive_url,
:headers => headers.dup,
@ -420,7 +481,14 @@ module Faraday
:request => options.dup)
end
# Internal: Yields username and password extracted from a URI if they both exist.
# Yields username and password extracted from a URI if they both exist.
#
# @param uri [URI]
# @yield [username, password] any username and password
# @yieldparam username [String] any username from URI
# @yieldparam password [String] any password from URI
# @return [void]
# @api private
def with_uri_credentials(uri)
if uri.user and uri.password
yield(Utils.unescape(uri.user), Utils.unescape(uri.password))

2
lib/faraday/error.rb
View File

@ -1,6 +1,8 @@
module Faraday
# Faraday error base class.
class Error < StandardError; end
# Faraday client error class.
class ClientError < Error
attr_reader :response, :wrapped_exception

12
lib/faraday/upload_io.rb
View File

@ -8,7 +8,7 @@ rescue LoadError
end
module Faraday
# Similar but not compatible with ::CompositeReadIO provided by multipart-post.
# Similar to, but not compatible with [::CompositeReadIO](https://github.com/nicksieger/multipart-post/blob/master/lib/composite_io.rb) provided by [multipart-post](https://github.com/nicksieger/multipart-post).
class CompositeReadIO
def initialize(*parts)
@parts = parts.flatten
@ -16,16 +16,23 @@ module Faraday
@index = 0
end
# @return [Integer] sum of the lengths of all the parts
def length
@parts.inject(0) { |sum, part| sum + part.length }
end
# Rewind each of the IOs and reset the index to 0.
#
# @return [void]
def rewind
@ios.each { |io| io.rewind }
@index = 0
end
# Read from IOs in order until `length` bytes have been received.
#
# @param length [Integer, nil]
# @param outbuf [String, nil]
def read(length = nil, outbuf = nil)
got_result = false
outbuf = outbuf ? outbuf.replace("") : ""
@ -43,6 +50,9 @@ module Faraday
(!got_result && length) ? nil : outbuf
end
# Close each of the IOs.
#
# @return [void]
def close
@ios.each { |io| io.close }
end