faraday 0.15.4 → 0.16.0

Sign up to get free protection for your applications and to get access to all the features.
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
-