faraday 0.15.4 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE.md +1 -1
  3. data/README.md +18 -344
  4. data/lib/faraday.rb +93 -175
  5. data/lib/faraday/adapter.rb +36 -22
  6. data/lib/faraday/adapter/em_http.rb +142 -99
  7. data/lib/faraday/adapter/em_http_ssl_patch.rb +23 -17
  8. data/lib/faraday/adapter/em_synchrony.rb +104 -60
  9. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +18 -15
  10. data/lib/faraday/adapter/excon.rb +100 -55
  11. data/lib/faraday/adapter/httpclient.rb +61 -39
  12. data/lib/faraday/adapter/net_http.rb +104 -51
  13. data/lib/faraday/adapter/net_http_persistent.rb +48 -27
  14. data/lib/faraday/adapter/patron.rb +54 -35
  15. data/lib/faraday/adapter/rack.rb +28 -12
  16. data/lib/faraday/adapter/test.rb +86 -53
  17. data/lib/faraday/adapter/typhoeus.rb +4 -1
  18. data/lib/faraday/adapter_registry.rb +28 -0
  19. data/lib/faraday/autoload.rb +47 -36
  20. data/lib/faraday/connection.rb +321 -179
  21. data/lib/faraday/dependency_loader.rb +37 -0
  22. data/lib/faraday/encoders/flat_params_encoder.rb +94 -0
  23. data/lib/faraday/encoders/nested_params_encoder.rb +171 -0
  24. data/lib/faraday/error.rb +67 -33
  25. data/lib/faraday/file_part.rb +128 -0
  26. data/lib/faraday/logging/formatter.rb +92 -0
  27. data/lib/faraday/middleware.rb +4 -28
  28. data/lib/faraday/middleware_registry.rb +129 -0
  29. data/lib/faraday/options.rb +35 -186
  30. data/lib/faraday/options/connection_options.rb +22 -0
  31. data/lib/faraday/options/env.rb +181 -0
  32. data/lib/faraday/options/proxy_options.rb +28 -0
  33. data/lib/faraday/options/request_options.rb +21 -0
  34. data/lib/faraday/options/ssl_options.rb +59 -0
  35. data/lib/faraday/param_part.rb +53 -0
  36. data/lib/faraday/parameters.rb +4 -197
  37. data/lib/faraday/rack_builder.rb +67 -56
  38. data/lib/faraday/request.rb +68 -36
  39. data/lib/faraday/request/authorization.rb +42 -30
  40. data/lib/faraday/request/basic_authentication.rb +14 -7
  41. data/lib/faraday/request/instrumentation.rb +45 -27
  42. data/lib/faraday/request/multipart.rb +79 -48
  43. data/lib/faraday/request/retry.rb +198 -169
  44. data/lib/faraday/request/token_authentication.rb +15 -10
  45. data/lib/faraday/request/url_encoded.rb +41 -23
  46. data/lib/faraday/response.rb +23 -16
  47. data/lib/faraday/response/logger.rb +22 -69
  48. data/lib/faraday/response/raise_error.rb +36 -14
  49. data/lib/faraday/utils.rb +28 -245
  50. data/lib/faraday/utils/headers.rb +139 -0
  51. data/lib/faraday/utils/params_hash.rb +61 -0
  52. data/spec/external_adapters/faraday_specs_setup.rb +14 -0
  53. metadata +21 -5
  54. data/lib/faraday/upload_io.rb +0 -67
@@ -1,12 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'faraday/adapter_registry'
4
+
1
5
  module Faraday
2
6
  # A Builder that processes requests into responses by passing through an inner
3
7
  # middleware stack (heavily inspired by Rack).
4
8
  #
5
- # Faraday::Connection.new(:url => 'http://sushi.com') do |builder|
9
+ # @example
10
+ # Faraday::Connection.new(url: 'http://sushi.com') do |builder|
6
11
  # builder.request :url_encoded # Faraday::Request::UrlEncoded
7
12
  # builder.adapter :net_http # Faraday::Adapter::NetHttp
8
13
  # end
9
14
  class RackBuilder
15
+ # Used to detect missing arguments
16
+ NO_ARGUMENT = Object.new
17
+
10
18
  attr_accessor :handlers
11
19
 
12
20
  # Error raised when trying to modify the stack after calling `lock!`
@@ -15,28 +23,28 @@ module Faraday
15
23
  # borrowed from ActiveSupport::Dependencies::Reference &
16
24
  # ActionDispatch::MiddlewareStack::Middleware
17
25
  class Handler
18
- @@constants_mutex = Mutex.new
19
- @@constants = Hash.new { |h, k|
20
- value = k.respond_to?(:constantize) ? k.constantize : Object.const_get(k)
21
- @@constants_mutex.synchronize { h[k] = value }
22
- }
26
+ REGISTRY = Faraday::AdapterRegistry.new
23
27
 
24
28
  attr_reader :name
25
29
 
26
30
  def initialize(klass, *args, &block)
27
31
  @name = klass.to_s
28
- if klass.respond_to?(:name)
29
- @@constants_mutex.synchronize { @@constants[@name] = klass }
30
- end
31
- @args, @block = args, block
32
+ REGISTRY.set(klass) if klass.respond_to?(:name)
33
+ @args = args
34
+ @block = block
32
35
  end
33
36
 
34
- def klass() @@constants[@name] end
35
- def inspect() @name end
37
+ def klass
38
+ REGISTRY.get(@name)
39
+ end
40
+
41
+ def inspect
42
+ @name
43
+ end
36
44
 
37
45
  def ==(other)
38
46
  if other.is_a? Handler
39
- self.name == other.name
47
+ name == other.name
40
48
  elsif other.respond_to? :name
41
49
  klass == other
42
50
  else
@@ -44,18 +52,19 @@ module Faraday
44
52
  end
45
53
  end
46
54
 
47
- def build(app)
55
+ def build(app = nil)
48
56
  klass.new(app, *@args, &@block)
49
57
  end
50
58
  end
51
59
 
52
- def initialize(handlers = [])
60
+ def initialize(handlers = [], adapter = nil, &block)
61
+ @adapter = adapter
53
62
  @handlers = handlers
54
63
  if block_given?
55
- build(&Proc.new)
64
+ build(&block)
56
65
  elsif @handlers.empty?
57
66
  # default stack, if nothing else is configured
58
- self.request :url_encoded
67
+ request :url_encoded
59
68
  self.adapter Faraday.default_adapter
60
69
  end
61
70
  end
@@ -64,13 +73,14 @@ module Faraday
64
73
  raise_if_locked
65
74
  @handlers.clear unless options[:keep]
66
75
  yield(self) if block_given?
76
+ adapter(Faraday.default_adapter) unless @adapter
67
77
  end
68
78
 
69
79
  def [](idx)
70
80
  @handlers[idx]
71
81
  end
72
82
 
73
- # Locks the middleware stack to ensure no further modifications are possible.
83
+ # Locks the middleware stack to ensure no further modifications are made.
74
84
  def lock!
75
85
  @handlers.freeze
76
86
  end
@@ -84,7 +94,7 @@ module Faraday
84
94
  use_symbol(Faraday::Middleware, klass, *args, &block)
85
95
  else
86
96
  raise_if_locked
87
- warn_middleware_after_adapter if adapter_set?
97
+ raise_if_adapter(klass)
88
98
  @handlers << self.class::Handler.new(klass, *args, &block)
89
99
  end
90
100
  end
@@ -97,8 +107,11 @@ module Faraday
97
107
  use_symbol(Faraday::Response, key, *args, &block)
98
108
  end
99
109
 
100
- def adapter(key, *args, &block)
101
- use_symbol(Faraday::Adapter, key, *args, &block)
110
+ def adapter(klass = NO_ARGUMENT, *args, &block)
111
+ return @adapter if klass == NO_ARGUMENT
112
+
113
+ klass = Faraday::Adapter.lookup_middleware(klass) if klass.is_a?(Symbol)
114
+ @adapter = self.class::Handler.new(klass, *args, &block)
102
115
  end
103
116
 
104
117
  ## methods to push onto the various positions in the stack:
@@ -106,12 +119,11 @@ module Faraday
106
119
  def insert(index, *args, &block)
107
120
  raise_if_locked
108
121
  index = assert_index(index)
109
- warn_middleware_after_adapter if inserting_after_adapter?(index)
110
122
  handler = self.class::Handler.new(*args, &block)
111
123
  @handlers.insert(index, handler)
112
124
  end
113
125
 
114
- alias_method :insert_before, :insert
126
+ alias insert_before insert
115
127
 
116
128
  def insert_after(index, *args, &block)
117
129
  index = assert_index(index)
@@ -133,13 +145,11 @@ module Faraday
133
145
  # Processes a Request into a Response by passing it through this Builder's
134
146
  # middleware stack.
135
147
  #
136
- # connection - Faraday::Connection
137
- # request - Faraday::Request
148
+ # @param connection [Faraday::Connection]
149
+ # @param request [Faraday::Request]
138
150
  #
139
- # Returns a Faraday::Response.
151
+ # @return [Faraday::Response]
140
152
  def build_response(connection, request)
141
- warn 'WARNING: No adapter was configured for this request' unless adapter_set?
142
-
143
153
  app.call(build_env(connection, request))
144
154
  end
145
155
 
@@ -153,26 +163,26 @@ module Faraday
153
163
  def app
154
164
  @app ||= begin
155
165
  lock!
156
- to_app(lambda { |env|
157
- response = Response.new
158
- env.response = response
159
- response.finish(env) unless env.parallel?
160
- response
161
- })
166
+ to_app
162
167
  end
163
168
  end
164
169
 
165
- def to_app(inner_app)
170
+ def to_app
166
171
  # last added handler is the deepest and thus closest to the inner app
167
- @handlers.reverse.inject(inner_app) { |app, handler| handler.build(app) }
172
+ # adapter is always the last one
173
+ @handlers.reverse.inject(@adapter.build) do |app, handler|
174
+ handler.build(app)
175
+ end
168
176
  end
169
177
 
170
178
  def ==(other)
171
- other.is_a?(self.class) && @handlers == other.handlers
179
+ other.is_a?(self.class) &&
180
+ @handlers == other.handlers &&
181
+ @adapter == other.adapter
172
182
  end
173
183
 
174
184
  def dup
175
- self.class.new(@handlers.dup)
185
+ self.class.new(@handlers.dup, @adapter.dup)
176
186
  end
177
187
 
178
188
  # ENV Keys
@@ -192,36 +202,36 @@ module Faraday
192
202
  # :password - Proxy server password
193
203
  # :ssl - Hash of options for configuring SSL requests.
194
204
  def build_env(connection, request)
195
- Env.new(request.method, request.body,
196
- connection.build_exclusive_url(request.path, request.params, request.options.params_encoder),
197
- request.options, request.headers, connection.ssl,
198
- connection.parallel_manager)
205
+ exclusive_url = connection.build_exclusive_url(
206
+ request.path, request.params,
207
+ request.options.params_encoder
208
+ )
209
+
210
+ Env.new(request.method, request.body, exclusive_url,
211
+ request.options, request.headers, connection.ssl,
212
+ connection.parallel_manager)
199
213
  end
200
214
 
201
215
  private
202
216
 
217
+ LOCK_ERR = "can't modify middleware stack after making a request"
218
+
203
219
  def raise_if_locked
204
- raise StackLocked, "can't modify middleware stack after making a request" if locked?
220
+ raise StackLocked, LOCK_ERR if locked?
205
221
  end
206
222
 
207
- def warn_middleware_after_adapter
208
- warn "WARNING: Unexpected middleware set after the adapter. " \
209
- "This won't be supported from Faraday 1.0."
210
- end
223
+ def raise_if_adapter(klass)
224
+ return unless is_adapter?(klass)
211
225
 
212
- def adapter_set?
213
- @handlers.any? { |handler| is_adapter?(handler) }
226
+ raise 'Adapter should be set using the `adapter` method, not `use`'
214
227
  end
215
228
 
216
- def inserting_after_adapter?(index)
217
- adapter_index = @handlers.find_index { |handler| is_adapter?(handler) }
218
- return false if adapter_index.nil?
219
-
220
- index > adapter_index
229
+ def adapter_set?
230
+ !@adapter.nil?
221
231
  end
222
232
 
223
- def is_adapter?(handler)
224
- handler.klass.ancestors.include? Faraday::Adapter
233
+ def is_adapter?(klass) # rubocop:disable Naming/PredicateName
234
+ klass.ancestors.include?(Faraday::Adapter)
225
235
  end
226
236
 
227
237
  def use_symbol(mod, key, *args, &block)
@@ -231,6 +241,7 @@ module Faraday
231
241
  def assert_index(index)
232
242
  idx = index.is_a?(Integer) ? index : @handlers.index(index)
233
243
  raise "No such handler: #{index.inspect}" unless idx
244
+
234
245
  idx
235
246
  end
236
247
  end
@@ -1,6 +1,9 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Faraday
2
- # Used to setup urls, params, headers, and the request body in a sane manner.
4
+ # Used to setup URLs, params, headers, and the request body in a sane manner.
3
5
  #
6
+ # @example
4
7
  # @connection.post do |req|
5
8
  # req.url 'http://localhost', 'a' => '1' # 'http://localhost?a=1'
6
9
  # req.headers['b'] = '2' # Header
@@ -9,25 +12,53 @@ module Faraday
9
12
  # req.body = 'abc'
10
13
  # end
11
14
  #
15
+ # @!attribute method
16
+ # @return [Symbol] the HTTP method of the Request
17
+ # @!attribute path
18
+ # @return [URI, String] the path
19
+ # @!attribute params
20
+ # @return [Hash] query parameters
21
+ # @!attribute headers
22
+ # @return [Faraday::Utils::Headers] headers
23
+ # @!attribute body
24
+ # @return [Hash] body
25
+ # @!attribute options
26
+ # @return [RequestOptions] options
27
+ #
28
+ # rubocop:disable Style/StructInheritance
12
29
  class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
30
+ # rubocop:enable Style/StructInheritance
31
+
13
32
  extend MiddlewareRegistry
14
33
 
15
- register_middleware File.expand_path('../request', __FILE__),
16
- :url_encoded => [:UrlEncoded, 'url_encoded'],
17
- :multipart => [:Multipart, 'multipart'],
18
- :retry => [:Retry, 'retry'],
19
- :authorization => [:Authorization, 'authorization'],
20
- :basic_auth => [:BasicAuthentication, 'basic_authentication'],
21
- :token_auth => [:TokenAuthentication, 'token_authentication'],
22
- :instrumentation => [:Instrumentation, 'instrumentation']
34
+ register_middleware File.expand_path('request', __dir__),
35
+ url_encoded: [:UrlEncoded, 'url_encoded'],
36
+ multipart: [:Multipart, 'multipart'],
37
+ retry: [:Retry, 'retry'],
38
+ authorization: [:Authorization, 'authorization'],
39
+ basic_auth: [
40
+ :BasicAuthentication,
41
+ 'basic_authentication'
42
+ ],
43
+ token_auth: [
44
+ :TokenAuthentication,
45
+ 'token_authentication'
46
+ ],
47
+ instrumentation: [:Instrumentation, 'instrumentation']
23
48
 
49
+ # @param request_method [String]
50
+ # @yield [request] for block customization, if block given
51
+ # @yieldparam request [Request]
52
+ # @return [Request]
24
53
  def self.create(request_method)
25
54
  new(request_method).tap do |request|
26
55
  yield(request) if block_given?
27
56
  end
28
57
  end
29
58
 
30
- # Public: Replace params, preserving the existing hash type
59
+ # Replace params, preserving the existing hash type.
60
+ #
61
+ # @param hash [Hash] new params
31
62
  def params=(hash)
32
63
  if params
33
64
  params.replace hash
@@ -36,7 +67,9 @@ module Faraday
36
67
  end
37
68
  end
38
69
 
39
- # Public: Replace request headers, preserving the existing hash type
70
+ # Replace request headers, preserving the existing hash type.
71
+ #
72
+ # @param hash [Hash] new headers
40
73
  def headers=(hash)
41
74
  if headers
42
75
  headers.replace hash
@@ -45,9 +78,14 @@ module Faraday
45
78
  end
46
79
  end
47
80
 
81
+ # Update path and params.
82
+ #
83
+ # @param path [URI, String]
84
+ # @param params [Hash, nil]
85
+ # @return [void]
48
86
  def url(path, params = nil)
49
87
  if path.respond_to? :query
50
- if query = path.query
88
+ if (query = path.query)
51
89
  path = path.dup
52
90
  path.query = nil
53
91
  end
@@ -61,25 +99,35 @@ module Faraday
61
99
  self.params.update(params) if params
62
100
  end
63
101
 
102
+ # @param key [Object] key to look up in headers
103
+ # @return [Object] value of the given header name
64
104
  def [](key)
65
105
  headers[key]
66
106
  end
67
107
 
108
+ # @param key [Object] key of header to write
109
+ # @param value [Object] value of header
68
110
  def []=(key, value)
69
111
  headers[key] = value
70
112
  end
71
113
 
114
+ # Marshal serialization support.
115
+ #
116
+ # @return [Hash] the hash ready to be serialized in Marshal.
72
117
  def marshal_dump
73
118
  {
74
- :method => method,
75
- :body => body,
76
- :headers => headers,
77
- :path => path,
78
- :params => params,
79
- :options => options
119
+ method: method,
120
+ body: body,
121
+ headers: headers,
122
+ path: path,
123
+ params: params,
124
+ options: options
80
125
  }
81
126
  end
82
127
 
128
+ # Marshal serialization support.
129
+ # Restores the instance variables according to the +serialised+.
130
+ # @param serialised [Hash] the serialised object.
83
131
  def marshal_load(serialised)
84
132
  self.method = serialised[:method]
85
133
  self.body = serialised[:body]
@@ -89,26 +137,10 @@ module Faraday
89
137
  self.options = serialised[:options]
90
138
  end
91
139
 
92
- # ENV Keys
93
- # :method - a symbolized request method (:get, :post)
94
- # :body - the request body that will eventually be converted to a string.
95
- # :url - URI instance for the current request.
96
- # :status - HTTP response status code
97
- # :request_headers - hash of HTTP Headers to be sent to the server
98
- # :response_headers - Hash of HTTP headers from the server
99
- # :parallel_manager - sent if the connection is in parallel mode
100
- # :request - Hash of options for configuring the request.
101
- # :timeout - open/read timeout Integer in seconds
102
- # :open_timeout - read timeout Integer in seconds
103
- # :proxy - Hash of proxy options
104
- # :uri - Proxy Server URI
105
- # :user - Proxy server username
106
- # :password - Proxy server password
107
- # :ssl - Hash of options for configuring SSL requests.
140
+ # @return [Env] the Env for this Request
108
141
  def to_env(connection)
109
142
  Env.new(method, body, connection.build_exclusive_url(path, params),
110
- options, headers, connection.ssl, connection.parallel_manager)
143
+ options, headers, connection.ssl, connection.parallel_manager)
111
144
  end
112
145
  end
113
146
  end
114
-
@@ -1,41 +1,53 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Faraday
2
- class Request::Authorization < Faraday::Middleware
3
- KEY = "Authorization".freeze unless defined? KEY
4
+ class Request
5
+ # Request middleware for the Authorization HTTP header
6
+ class Authorization < Faraday::Middleware
7
+ KEY = 'Authorization' unless defined? KEY
4
8
 
5
- # Public
6
- def self.header(type, token)
7
- case token
8
- when String, Symbol
9
- "#{type} #{token}"
10
- when Hash
11
- build_hash(type.to_s, token)
12
- else
13
- raise ArgumentError, "Can't build an Authorization #{type} header from #{token.inspect}"
9
+ # @param type [String, Symbol]
10
+ # @param token [String, Symbol, Hash]
11
+ # @return [String] a header value
12
+ def self.header(type, token)
13
+ case token
14
+ when String, Symbol
15
+ "#{type} #{token}"
16
+ when Hash
17
+ build_hash(type.to_s, token)
18
+ else
19
+ raise ArgumentError,
20
+ "Can't build an Authorization #{type}" \
21
+ "header from #{token.inspect}"
22
+ end
14
23
  end
15
- end
16
24
 
17
- # Internal
18
- def self.build_hash(type, hash)
19
- comma = ", "
20
- values = []
21
- hash.each do |key, value|
22
- values << "#{key}=#{value.to_s.inspect}"
25
+ # @param type [String]
26
+ # @param hash [Hash]
27
+ # @return [String] type followed by comma-separated key=value pairs
28
+ # @api private
29
+ def self.build_hash(type, hash)
30
+ comma = ', '
31
+ values = []
32
+ hash.each do |key, value|
33
+ values << "#{key}=#{value.to_s.inspect}"
34
+ end
35
+ "#{type} #{values * comma}"
23
36
  end
24
- "#{type} #{values * comma}"
25
- end
26
37
 
27
- def initialize(app, type, token)
28
- @header_value = self.class.header(type, token)
29
- super(app)
30
- end
38
+ # @param app [#call]
39
+ # @param type [String, Symbol] Type of Authorization
40
+ # @param token [String, Symbol, Hash] Token value for the Authorization
41
+ def initialize(app, type, token)
42
+ @header_value = self.class.header(type, token)
43
+ super(app)
44
+ end
31
45
 
32
- # Public
33
- def call(env)
34
- unless env.request_headers[KEY]
35
- env.request_headers[KEY] = @header_value
46
+ # @param env [Faraday::Env]
47
+ def call(env)
48
+ env.request_headers[KEY] = @header_value unless env.request_headers[KEY]
49
+ @app.call(env)
36
50
  end
37
- @app.call(env)
38
51
  end
39
52
  end
40
53
  end
41
-