diff --git a/README.md b/README.md index 152fa0b45..a409cd401 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,15 @@ Faraday supports these adapters out of the box: * [Net::HTTP][net_http] _(default)_ * [Net::HTTP::Persistent][persistent] -* [Excon][] -* [Patron][] -* [EventMachine][] -* [HTTPClient][] +* [Excon][excon] +* [Patron][patron] +* [EventMachine][eventmachine] +* [HTTPClient][httpclient] Adapters are slowly being moved into their own gems, or bundled with HTTP clients. Here is the list of known external adapters: -* [Typhoeus][] +* [Typhoeus][typhoeus] It also includes a Rack adapter for hitting loaded Rack applications through Rack::Test, and a Test adapter for stubbing requests by hand. @@ -70,7 +70,7 @@ conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday| end ``` -Once you have the connection object, use it to make HTTP requests. You can pass paramters to it in a few different ways: +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 ## diff --git a/lib/faraday/connection.rb b/lib/faraday/connection.rb index 517bf6cd7..0ef6ff569 100644 --- a/lib/faraday/connection.rb +++ b/lib/faraday/connection.rb @@ -39,8 +39,8 @@ class Connection # Public: Sets the default parallel manager for this connection. attr_writer :default_parallel_manager - # Public: Gets or Sets the Hash proxy options. - # attr_reader :proxy + # Public: Gets the Hash proxy options. + attr_reader :proxy # Public: Initializes a new Faraday::Connection. # @@ -275,14 +275,6 @@ def in_parallel(manager = nil) @parallel_manager = nil end - # Public: Gets or Sets the Hash proxy options. - def proxy(arg = nil) - return @proxy if arg.nil? - warn 'Warning: use of proxy(new_value) to set connection proxy have been DEPRECATED and will be removed in Faraday 1.0' - @manual_proxy = true - @proxy = ProxyOptions.from(arg) - end - # Public: Sets the Hash proxy options. def proxy=(new_value) @manual_proxy = true diff --git a/lib/faraday/error.rb b/lib/faraday/error.rb index b6d49982d..dde5f6c0d 100644 --- a/lib/faraday/error.rb +++ b/lib/faraday/error.rb @@ -1,6 +1,5 @@ module Faraday class Error < StandardError; end - class MissingDependency < Error; end class ClientError < Error attr_reader :response, :wrapped_exception @@ -56,7 +55,7 @@ def initialize(ex = nil) class SSLError < ClientError end - [:MissingDependency, :ClientError, :ConnectionFailed, :ResourceNotFound, + [:ClientError, :ConnectionFailed, :ResourceNotFound, :ParsingError, :TimeoutError, :SSLError].each do |const| Error.const_set(const, Faraday.const_get(const)) end diff --git a/lib/faraday/options.rb b/lib/faraday/options.rb index 302d1215a..c7e9a858a 100644 --- a/lib/faraday/options.rb +++ b/lib/faraday/options.rb @@ -268,6 +268,50 @@ def new_builder(block) end end + # @!attribute method + # @return [Symbol] HTTP method (`:get`, `:post`) + # + # @!attribute body + # @return [String] The request body that will eventually be converted to a string. + # + # @!attribute url + # @return [URI] URI instance for the current request. + # + # @!attribute request + # @return [Hash] options for configuring the request. + # Options for configuring the request. + # + # - `:timeout` open/read timeout Integer in seconds + # - `:open_timeout` - read timeout Integer in seconds + # - `:on_data` - Proc for streaming + # - `:proxy` - Hash of proxy options + # - `:uri` - Proxy Server URI + # - `:user` - Proxy server username + # - `:password` - Proxy server password + # + # @!attribute request_headers + # @return [Hash] HTTP Headers to be sent to the server. + # + # @!attribute ssl + # @return [Hash] options for configuring SSL requests + # + # @!attribute parallel_manager + # @return [Object] sent if the connection is in parallel mode + # + # @!attribute params + # @return [Hash] + # + # @!attribute response + # @return [Response] + # + # @!attribute response_headers + # @return [Hash] HTTP headers from the server + # + # @!attribute status + # @return [Integer] HTTP response status code + # + # @!attribute reason_phrase + # @return [String] class Env < Options.new(:method, :body, :url, :request, :request_headers, :ssl, :parallel_manager, :params, :response, :response_headers, :status, :reason_phrase) @@ -287,7 +331,10 @@ class Env < Options.new(:method, :body, :url, :request, :request_headers, def_delegators :request, :params_encoder - # Public + # Build a new Env from given value. Respects and updates `custom_members`. + # + # @param value [Object] a value fitting Option.from(v). + # @return [Env] from given value def self.from(value) env = super(value) if value.respond_to?(:custom_members) @@ -296,7 +343,7 @@ def self.from(value) env end - # Public + # @param key [Object] def [](key) if in_member_set?(key) super(key) @@ -305,7 +352,8 @@ def [](key) end end - # Public + # @param key [Object] + # @param value [Object] def []=(key, value) if in_member_set?(key) super(key, value) @@ -314,28 +362,28 @@ def []=(key, value) end end - # Public + # @return [Boolean] true if status is in the set of {SuccessfulStatuses}. def success? SuccessfulStatuses.include?(status) end - # Public + # @return [Boolean] true if there's no body yet, and the method is in the set of {MethodsWithBodies}. def needs_body? !body && MethodsWithBodies.include?(method) end - # Public + # Sets content length to zero and the body to the empty string. def clear_body request_headers[ContentLength] = '0' self.body = '' end - # Public + # @return [Boolean] true if the status isn't in the set of {StatusesWithoutBody}. def parse_body? !StatusesWithoutBody.include?(status) end - # Public + # @return [Boolean] true if there is a parallel_manager def parallel? !!parallel_manager end @@ -353,12 +401,12 @@ def inspect %(#<#{self.class}#{attrs.join(" ")}>) end - # Internal + # @private def custom_members @custom_members ||= {} end - # Internal + # @private if members.first.is_a?(Symbol) def in_member_set?(key) self.class.member_set.include?(key.to_sym) @@ -369,7 +417,7 @@ def in_member_set?(key) end end - # Internal + # @private def self.member_set @member_set ||= Set.new(members) end diff --git a/lib/faraday/parameters.rb b/lib/faraday/parameters.rb index 8cf43c3d5..58114335b 100644 --- a/lib/faraday/parameters.rb +++ b/lib/faraday/parameters.rb @@ -1,12 +1,20 @@ require "forwardable" module Faraday + # This is the default encoder for Faraday requests. + # Using this encoder, parameters will be encoded respecting their structure, + # so you can send objects such as Arrays or Hashes as parameters for your requests. module NestedParamsEncoder class << self extend Forwardable def_delegators :'Faraday::Utils', :escape, :unescape end + # @param params [nil, Array, #to_hash] parameters to be encoded + # + # @return [String] the encoded params + # + # @raise [TypeError] if params can not be converted to a Hash def self.encode(params) return nil if params == nil @@ -63,6 +71,11 @@ def self.encode(params) return buffer.chop end + # @param query [nil, String] + # + # @return [Array] the decoded params + # + # @raise [TypeError] if the nesting is incorrect def self.decode(query) return nil if query == nil @@ -114,6 +127,7 @@ def self.decode(query) # Internal: convert a nested hash with purely numeric keys into an array. # FIXME: this is not compatible with Rack::Utils.parse_nested_query + # @!visibility private def self.dehash(hash, depth) hash.each do |key, value| hash[key] = dehash(value, depth + 1) if value.kind_of?(Hash) diff --git a/lib/faraday/request.rb b/lib/faraday/request.rb index 828108304..9d09c6c2b 100644 --- a/lib/faraday/request.rb +++ b/lib/faraday/request.rb @@ -1,6 +1,7 @@ module Faraday - # Used to setup urls, params, headers, and the request body in a sane manner. + # Used to setup URLs, params, headers, and the request body in a sane manner. # + # @example # @connection.post do |req| # req.url 'http://localhost', 'a' => '1' # 'http://localhost?a=1' # req.headers['b'] = '2' # Header @@ -9,6 +10,18 @@ module Faraday # req.body = 'abc' # end # + # @!attribute method + # @return [Symbol] the HTTP method of the Request + # @!attribute path + # @return [URI, String] the path + # @!attribute params + # @return [Hash] query parameters + # @!attribute headers + # @return [Faraday::Utils::Headers] headers + # @!attribute body + # @return [Hash] body + # @!attribute options + # @return [RequestOptions] options class Request < Struct.new(:method, :path, :params, :headers, :body, :options) extend MiddlewareRegistry @@ -21,13 +34,19 @@ class Request < Struct.new(:method, :path, :params, :headers, :body, :options) :token_auth => [:TokenAuthentication, 'token_authentication'], :instrumentation => [:Instrumentation, 'instrumentation'] + # @param request_method [String] + # @yield [request] for block customization, if block given + # @yieldparam request [Request] + # @return [Request] def self.create(request_method) new(request_method).tap do |request| yield(request) if block_given? end end - # Public: Replace params, preserving the existing hash type + # Replace params, preserving the existing hash type. + # + # @param hash [Hash] new params def params=(hash) if params params.replace hash @@ -36,7 +55,9 @@ def params=(hash) end end - # Public: Replace request headers, preserving the existing hash type + # Replace request headers, preserving the existing hash type. + # + # @param hash [Hash] new headers def headers=(hash) if headers headers.replace hash @@ -45,6 +66,11 @@ def headers=(hash) end end + # Update path and params. + # + # @param path [URI, String] + # @param params [Hash, nil] + # @return [void] def url(path, params = nil) if path.respond_to? :query if query = path.query @@ -61,31 +87,19 @@ def url(path, params = nil) self.params.update(params) if params end + # @param key [Object] key to look up in headers + # @return [Object] value of the given header name def [](key) headers[key] end + # @param key [Object] key of header to write + # @param value [Object] value of header def []=(key, value) headers[key] = value end - # ENV Keys - # :method - a symbolized request method (:get, :post) - # :body - the request body that will eventually be converted to a string. - # :url - URI instance for the current request. - # :status - HTTP response status code - # :request_headers - hash of HTTP Headers to be sent to the server - # :response_headers - Hash of HTTP headers from the server - # :parallel_manager - sent if the connection is in parallel mode - # :request - Hash of options for configuring the request. - # :timeout - open/read timeout Integer in seconds - # :open_timeout - read timeout Integer in seconds - # :on_data - Proc for streaming - # :proxy - Hash of proxy options - # :uri - Proxy Server URI - # :user - Proxy server username - # :password - Proxy server password - # :ssl - Hash of options for configuring SSL requests. + # @return [Env] the Env for this Request def to_env(connection) Env.new(method, body, connection.build_exclusive_url(path, params), options, headers, connection.ssl, connection.parallel_manager)