faraday 0.9.2 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (102) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +276 -0
  3. data/LICENSE.md +1 -1
  4. data/README.md +27 -217
  5. data/Rakefile +7 -0
  6. data/examples/client_spec.rb +65 -0
  7. data/examples/client_test.rb +79 -0
  8. data/lib/faraday/adapter/em_http.rb +150 -101
  9. data/lib/faraday/adapter/em_http_ssl_patch.rb +25 -19
  10. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +18 -15
  11. data/lib/faraday/adapter/em_synchrony.rb +106 -56
  12. data/lib/faraday/adapter/excon.rb +98 -55
  13. data/lib/faraday/adapter/httpclient.rb +90 -55
  14. data/lib/faraday/adapter/net_http.rb +143 -54
  15. data/lib/faraday/adapter/net_http_persistent.rb +70 -28
  16. data/lib/faraday/adapter/patron.rb +92 -38
  17. data/lib/faraday/adapter/rack.rb +30 -13
  18. data/lib/faraday/adapter/test.rb +136 -52
  19. data/lib/faraday/adapter/typhoeus.rb +7 -115
  20. data/lib/faraday/adapter.rb +89 -20
  21. data/lib/faraday/adapter_registry.rb +30 -0
  22. data/lib/faraday/autoload.rb +47 -36
  23. data/lib/faraday/connection.rb +345 -168
  24. data/lib/faraday/dependency_loader.rb +37 -0
  25. data/lib/faraday/encoders/flat_params_encoder.rb +98 -0
  26. data/lib/faraday/encoders/nested_params_encoder.rb +171 -0
  27. data/lib/faraday/error.rb +108 -29
  28. data/lib/faraday/file_part.rb +128 -0
  29. data/lib/faraday/logging/formatter.rb +105 -0
  30. data/lib/faraday/middleware.rb +12 -28
  31. data/lib/faraday/middleware_registry.rb +129 -0
  32. data/lib/faraday/options/connection_options.rb +22 -0
  33. data/lib/faraday/options/env.rb +181 -0
  34. data/lib/faraday/options/proxy_options.rb +28 -0
  35. data/lib/faraday/options/request_options.rb +22 -0
  36. data/lib/faraday/options/ssl_options.rb +59 -0
  37. data/lib/faraday/options.rb +57 -194
  38. data/lib/faraday/param_part.rb +53 -0
  39. data/lib/faraday/parameters.rb +4 -196
  40. data/lib/faraday/rack_builder.rb +74 -39
  41. data/lib/faraday/request/authorization.rb +44 -31
  42. data/lib/faraday/request/basic_authentication.rb +14 -7
  43. data/lib/faraday/request/instrumentation.rb +45 -27
  44. data/lib/faraday/request/multipart.rb +81 -45
  45. data/lib/faraday/request/retry.rb +211 -126
  46. data/lib/faraday/request/token_authentication.rb +15 -10
  47. data/lib/faraday/request/url_encoded.rb +43 -23
  48. data/lib/faraday/request.rb +84 -30
  49. data/lib/faraday/response/logger.rb +22 -48
  50. data/lib/faraday/response/raise_error.rb +38 -14
  51. data/lib/faraday/response.rb +31 -17
  52. data/lib/faraday/utils/headers.rb +139 -0
  53. data/lib/faraday/utils/params_hash.rb +61 -0
  54. data/lib/faraday/utils.rb +36 -228
  55. data/lib/faraday.rb +103 -205
  56. data/spec/external_adapters/faraday_specs_setup.rb +14 -0
  57. data/spec/faraday/adapter/em_http_spec.rb +47 -0
  58. data/spec/faraday/adapter/em_synchrony_spec.rb +16 -0
  59. data/spec/faraday/adapter/excon_spec.rb +49 -0
  60. data/spec/faraday/adapter/httpclient_spec.rb +73 -0
  61. data/spec/faraday/adapter/net_http_persistent_spec.rb +57 -0
  62. data/spec/faraday/adapter/net_http_spec.rb +64 -0
  63. data/spec/faraday/adapter/patron_spec.rb +18 -0
  64. data/spec/faraday/adapter/rack_spec.rb +8 -0
  65. data/spec/faraday/adapter/typhoeus_spec.rb +7 -0
  66. data/spec/faraday/adapter_registry_spec.rb +28 -0
  67. data/spec/faraday/adapter_spec.rb +55 -0
  68. data/spec/faraday/composite_read_io_spec.rb +80 -0
  69. data/spec/faraday/connection_spec.rb +691 -0
  70. data/spec/faraday/error_spec.rb +45 -0
  71. data/spec/faraday/middleware_spec.rb +26 -0
  72. data/spec/faraday/options/env_spec.rb +70 -0
  73. data/spec/faraday/options/options_spec.rb +297 -0
  74. data/spec/faraday/options/proxy_options_spec.rb +37 -0
  75. data/spec/faraday/options/request_options_spec.rb +19 -0
  76. data/spec/faraday/params_encoders/flat_spec.rb +34 -0
  77. data/spec/faraday/params_encoders/nested_spec.rb +134 -0
  78. data/spec/faraday/rack_builder_spec.rb +196 -0
  79. data/spec/faraday/request/authorization_spec.rb +88 -0
  80. data/spec/faraday/request/instrumentation_spec.rb +76 -0
  81. data/spec/faraday/request/multipart_spec.rb +274 -0
  82. data/spec/faraday/request/retry_spec.rb +242 -0
  83. data/spec/faraday/request/url_encoded_spec.rb +83 -0
  84. data/spec/faraday/request_spec.rb +109 -0
  85. data/spec/faraday/response/logger_spec.rb +220 -0
  86. data/spec/faraday/response/middleware_spec.rb +68 -0
  87. data/spec/faraday/response/raise_error_spec.rb +106 -0
  88. data/spec/faraday/response_spec.rb +75 -0
  89. data/spec/faraday/utils/headers_spec.rb +82 -0
  90. data/spec/faraday/utils_spec.rb +56 -0
  91. data/spec/faraday_spec.rb +37 -0
  92. data/spec/spec_helper.rb +132 -0
  93. data/spec/support/disabling_stub.rb +14 -0
  94. data/spec/support/fake_safe_buffer.rb +15 -0
  95. data/spec/support/helper_methods.rb +133 -0
  96. data/spec/support/shared_examples/adapter.rb +104 -0
  97. data/spec/support/shared_examples/params_encoder.rb +18 -0
  98. data/spec/support/shared_examples/request_method.rb +234 -0
  99. data/spec/support/streaming_response_checker.rb +35 -0
  100. data/spec/support/webmock_rack_app.rb +68 -0
  101. metadata +110 -64
  102. data/lib/faraday/upload_io.rb +0 -67
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 1d23ec0aefc40d23ccc4410db08092bd29e477309fb8aa6794b3c8401961de10
4
+ data.tar.gz: c33ca7313dcccbf148266a80aa4e12d4cba96a4feb96ecfc3e8ff50fa06756c5
5
+ SHA512:
6
+ metadata.gz: 8058c22dc6e78bc3d46a9c8a22c458656a1380a4aed62b31e11b9b054fc6791373dd103276fc018148daed3934a724bcb39390bbe88e2762281ff810b61b408d
7
+ data.tar.gz: 341f3b44148f666bb03f8e7b232fd92e26b8c34d758090e6e82f1276af29ff17d4f62bdb58871254ba48b2232ab58269c71db08df7a4b0c35c53f2c7e9bbe7e8
data/CHANGELOG.md ADDED
@@ -0,0 +1,276 @@
1
+ # Faraday Changelog
2
+
3
+ ## v1.0
4
+
5
+ Features:
6
+
7
+ * Add #trace support to Faraday::Connection #861 (@technoweenie)
8
+ * Add the log formatter that is easy to override and safe to inherit #889 (@prikha)
9
+ * Support standalone adapters #941 (@iMacTia)
10
+ * Introduce Faraday::ConflictError for 409 response code #979 (@lucasmoreno)
11
+ * Add support for setting `read_timeout` option separately #1003 (@springerigor)
12
+ * Refactor and cleanup timeout settings across adapters #1022 (@technoweenie)
13
+ * Create ParamPart class to allow multipart posts with JSON content and file upload at the same time #1017 (@jeremy-israel)
14
+ * Copy UploadIO const -> FilePart for consistency with ParamPart #1018, #1021 (@technoweenie)
15
+ * Implement streaming responses in the Excon adapter #1026 (@technoweenie)
16
+ * Add default implementation of `Middleware#close`. #1069 (@ioquatix)
17
+ * Add `Adapter#close` so that derived classes can call super. #1091 (@ioquatix)
18
+ * Add log_level option to logger default formatter #1079 (@amrrbakry)
19
+ * Fix empty array for FlatParamsEncoder `{key: []} -> "key="` #1084 (@mrexox)
20
+
21
+ Bugs:
22
+
23
+ * Explicitly require date for DateTime library in Retry middleware #844 (@nickpresta)
24
+ * Refactor Adapter as final endpoints #846 (@iMacTia)
25
+ * Separate Request and Response bodies in Faraday::Env #847 (@iMacTia)
26
+ * Implement Faraday::Connection#options to make HTTP requests with the OPTIONS verb. #857 (@technoweenie)
27
+ * Multipart: Drop Ruby 1.8 String behavior compat #892 (@olleolleolle)
28
+ * Fix Ruby warnings in Faraday::Options.memoized #962 (@technoweenie)
29
+ * Allow setting min/max SSL version for a Net::HTTP::Persistent connection #972, #973 (@bdewater, @olleolleolle)
30
+ * Fix instances of frozen empty string literals #1040 (@BobbyMcWho)
31
+ * remove temp_proxy and improve proxy tests #1063 (@technoweenie)
32
+ * improve error initializer consistency #1095 (@technoweenie)
33
+
34
+ Misc:
35
+
36
+ * Convert minitest suite to RSpec #832 (@iMacTia, with help from @gaynetdinov, @Insti, @technoweenie)
37
+ * Major effort to update code to RuboCop standards. #854 (@olleolleolle, @iMacTia, @technoweenie, @htwroclau, @jherdman, @Drenmi, @Insti)
38
+ * Rubocop #1044, #1047 (@BobbyMcWho, @olleolleolle)
39
+ * Documentation tweaks (@adsteel, @Hubro, @iMacTia, @olleolleolle, @technoweenie)
40
+ * Update license year #981 (@Kevin-Kawai)
41
+ * Configure Jekyll plugin jekyll-remote-theme to support Docker usage #999 (@Lewiscowles1986)
42
+ * Fix Ruby 2.7 warnings #1009 (@tenderlove)
43
+ * Cleanup adapter connections #1023 (@technoweenie)
44
+ * Describe clearing cached stubs #1045 (@viraptor)
45
+ * Add project metadata to the gemspec #1046 (@orien)
46
+
47
+ ## v0.17.3
48
+
49
+ Fixes:
50
+
51
+ * Reverts changes in error classes hierarchy. #1092 (@iMacTia)
52
+ * Fix Ruby 1.9 syntax errors and improve Error class testing #1094 (@BanzaiMan,
53
+ @mrexox, @technoweenie)
54
+
55
+ Misc:
56
+
57
+ * Stops using `&Proc.new` for block forwarding. #1083 (@olleolleolle)
58
+ * Update CI to test against ruby 2.0-2.7 #1087, #1099 (@iMacTia, @olleolleolle,
59
+ @technoweenie)
60
+ * require FARADAY_DEPRECATE=warn to show Faraday v1.0 deprecation warnings
61
+ #1098 (@technoweenie)
62
+
63
+ ## v0.17.1
64
+
65
+ Final release before Faraday v1.0, with important fixes for Ruby 2.7.
66
+
67
+ Fixes:
68
+
69
+ * RaiseError response middleware raises exception if HTTP client returns a nil
70
+ status. #1042 (@jonnyom, @BobbyMcWho)
71
+
72
+ Misc:
73
+
74
+ * Fix Ruby 2.7 warnings (#1009)
75
+ * Add `Faraday::Deprecate` to warn about upcoming v1.0 changes. (#1054, #1059,
76
+ #1076, #1077)
77
+ * Add release notes up to current in CHANGELOG.md (#1066)
78
+ * Port minimal rspec suite from main branch to run backported tests. (#1058)
79
+
80
+ ## v0.17.0
81
+
82
+ This release is the same as v0.15.4. It was pushed to cover up releases
83
+ v0.16.0-v0.16.2.
84
+
85
+ ## v0.15.4
86
+
87
+ * Expose `pool_size` as a option for the NetHttpPersistent adapter (#834)
88
+
89
+ ## v0.15.3
90
+
91
+ * Make Faraday::Request serialisable with Marshal. (#803)
92
+ * Add DEFAULT_EXCEPTIONS constant to Request::Retry (#814)
93
+ * Add support for Ruby 2.6 Net::HTTP write_timeout (#824)
94
+
95
+ ## v0.15.2
96
+
97
+ * Prevents `Net::HTTP` adapters to retry request internally by setting `max_retries` to 0 if available (Ruby 2.5+). (#799)
98
+ * Fixes `NestedParamsEncoder` handling of empty array values (#801)
99
+
100
+ ## v0.15.1
101
+
102
+ * NetHttpPersistent adapter better reuse of SSL connections (#793)
103
+ * Refactor: inline cached_connection (#797)
104
+ * Logger middleware: use $stdout instead of STDOUT (#794)
105
+ * Fix: do not memoize/reuse Patron session (#796)
106
+
107
+ Also in this release:
108
+
109
+ * Allow setting min/max ssl version for Net::HTTP (#792)
110
+ * Allow setting min/max ssl version for Excon (#795)
111
+
112
+ ## v0.15.0
113
+
114
+ Features:
115
+
116
+ * Added retry block option to retry middleware. (#770)
117
+ * Retry middleware improvements (honour Retry-After header, retry statuses) (#773)
118
+ * Improve response logger middleware output (#784)
119
+
120
+ Fixes:
121
+
122
+ * Remove unused class error (#767)
123
+ * Fix minor typo in README (#760)
124
+ * Reuse persistent connections when using net-http-persistent (#778)
125
+ * Fix Retry middleware documentation (#781)
126
+ * Returns the http response when giving up on retrying by status (#783)
127
+
128
+ ## v0.14.0
129
+
130
+ Features:
131
+
132
+ * Allow overriding env proxy #754 (@iMacTia)
133
+ * Remove legacy Typhoeus adapter #715 (@olleolleolle)
134
+ * External Typhoeus Adapter Compatibility #748 (@iMacTia)
135
+ * Warn about missing adapter when making a request #743 (@antstorm)
136
+ * Faraday::Adapter::Test stubs now support entire urls (with host) #741 (@erik-escobedo)
137
+
138
+ Fixes:
139
+
140
+ * If proxy is manually provided, this takes priority over `find_proxy` #724 (@iMacTia)
141
+ * Fixes the behaviour for Excon's open_timeout (not setting write_timeout anymore) #731 (@apachelogger)
142
+ * Handle all connection timeout messages in Patron #687 (@stayhero)
143
+
144
+ ## v0.13.1
145
+
146
+ * Fixes an incompatibility with Addressable::URI being used as uri_parser
147
+
148
+ ## v0.13.0
149
+
150
+ Features:
151
+
152
+ * Dynamically reloads the proxy when performing a request on an absolute domain (#701)
153
+ * Adapter support for Net::HTTP::Persistent v3.0.0 (#619)
154
+
155
+ Fixes:
156
+
157
+ * Prefer #hostname over #host. (#714)
158
+ * Fixes an edge-case issue with response headers parsing (missing HTTP header) (#719)
159
+
160
+ ## v0.12.2
161
+
162
+ * Parse headers from aggregated proxy requests/responses (#681)
163
+ * Guard against invalid middleware configuration with warning (#685)
164
+ * Do not use :insecure option by default in Patron (#691)
165
+ * Fixes an issue with HTTPClient not raising a `Faraday::ConnectionFailed` (#702)
166
+ * Fixes YAML serialization/deserialization for `Faraday::Utils::Headers` (#690)
167
+ * Fixes an issue with Options having a nil value (#694)
168
+ * Fixes an issue with Faraday.default_connection not using Faraday.default_connection_options (#698)
169
+ * Fixes an issue with Options.merge! and Faraday instrumentation middleware (#710)
170
+
171
+ ## v0.12.1
172
+
173
+ * Fix an issue with Patron tests failing on jruby
174
+ * Fix an issue with new `rewind_files` feature that was causing an exception when the body was not an Hash
175
+ * Expose wrapped_exception in all client errors
176
+ * Add Authentication Section to the ReadMe
177
+
178
+ ## v0.12.0.1
179
+
180
+ * Hotfix release to address an issue with TravisCI deploy on Rubygems
181
+
182
+ ## v0.12.0
183
+
184
+ Features:
185
+
186
+ * Proxy feature now relies on Ruby `URI::Generic#find_proxy` and can use `no_proxy` ENV variable (not compatible with ruby < 2.0)
187
+ * Adds support for `context` request option to pass arbitrary information to middlewares
188
+
189
+ Fixes:
190
+
191
+ * Fix an issue with options that was causing new options to override defaults ones unexpectedly
192
+ * Rewind `UploadIO`s on retry to fix a compatibility issue
193
+ * Make multipart boundary unique
194
+ * Improvements in `README.md`
195
+
196
+ ## v0.11.0
197
+
198
+ Features:
199
+
200
+ * Add `filter` method to Logger middleware
201
+ * Add support for Ruby2.4 and Minitest 6
202
+ * Introduce block syntax to customise the adapter
203
+
204
+ Fixes:
205
+
206
+ * Fix an issue that was allowing to override `default_connection_options` from a connection instance
207
+ * Fix a bug that was causing newline escape characters ("\n") to be used when building the Authorization header
208
+
209
+ ## v0.10.1
210
+
211
+ - Fix an issue with HTTPClient adapter that was causing the SSL to be reset on every request
212
+ - Rescue `IOError` instead of specific subclass
213
+ - `Faraday::Utils::Headers` can now be successfully serialised in YAML
214
+ - Handle `default_connection_options` set with hash
215
+
216
+ ## v0.10.0
217
+
218
+ Breaking changes:
219
+ - Drop support for Ruby 1.8
220
+
221
+ Features:
222
+ - Include wrapped exception/reponse in ClientErrors
223
+ - Add `response.reason_phrase`
224
+ - Provide option to selectively skip logging request/response headers
225
+ - Add regex support for pattern matching in `test` adapter
226
+
227
+ Fixes:
228
+ - Add `Faraday.respond_to?` to find methods managed by `method_missing`
229
+ - em-http: `request.host` instead of `connection.host` should be taken for SSL validations
230
+ - Allow `default_connection_options` to be merged when options are passed as url parameter
231
+ - Improve splitting key-value pairs in raw HTTP headers
232
+
233
+ ## v0.9.2
234
+
235
+ Adapters:
236
+ - Enable gzip compression for httpclient
237
+ - Fixes default certificate store for httpclient not having default paths.
238
+ - Make excon adapter compatible with 0.44 excon version
239
+ - Add compatibility with Patron 0.4.20
240
+ - Determine default port numbers in Net::HTTP adapters (Addressable compatibility)
241
+ - em-http: wrap "connection closed by server" as ConnectionFailed type
242
+ - Wrap Errno::ETIMEDOUT in Faraday::Error::TimeoutError
243
+
244
+ Utils:
245
+ - Add Rack-compatible support for parsing `a[][b]=c` nested queries
246
+ - Encode nil values in queries different than empty strings. Before: `a=`; now: `a`.
247
+ - Have `Faraday::Utils::Headers#replace` clear internal key cache
248
+ - Dup the internal key cache when a Headers hash is copied
249
+
250
+ Env and middleware:
251
+ - Ensure `env` stored on middleware response has reference to the response
252
+ - Ensure that Response properties are initialized during `on_complete` (VCR compatibility)
253
+ - Copy request options in Faraday::Connection#dup
254
+ - Env custom members should be copied by Env.from(env)
255
+ - Honour per-request `request.options.params_encoder`
256
+ - Fix `interval_randomness` data type for Retry middleware
257
+ - Add maximum interval option for Retry middleware
258
+
259
+ ## v0.9.1
260
+
261
+ * Refactor Net:HTTP adapter so that with_net_http_connection can be overridden to allow pooled connections. (@Ben-M)
262
+ * Add configurable methods that bypass `retry_if` in the Retry request middleware. (@mike-bourgeous)
263
+
264
+ ## v0.9.0
265
+
266
+ * Add HTTPClient adapter (@hakanensari)
267
+ * Improve Retry handler (@mislav)
268
+ * Remove autoloading by default (@technoweenie)
269
+ * Improve internal docs (@technoweenie, @mislav)
270
+ * Respect user/password in http proxy string (@mislav)
271
+ * Adapter options are structs. Reinforces consistent options across adapters
272
+ (@technoweenie)
273
+ * Stop stripping trailing / off base URLs in a Faraday::Connection. (@technoweenie)
274
+ * Add a configurable URI parser. (@technoweenie)
275
+ * Remove need to manually autoload when using the authorization header helpers on `Faraday::Connection`. (@technoweenie)
276
+ * `Faraday::Adapter::Test` respects the `Faraday::RequestOptions#params_encoder` option. (@technoweenie)
data/LICENSE.md CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2009-2015 Rick Olson, Zack Hobson
1
+ Copyright (c) 2009-2019 Rick Olson, Zack Hobson
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
data/README.md CHANGED
@@ -1,223 +1,32 @@
1
- # Faraday
1
+ # [![Faraday](./docs/assets/img/repo-card-slim.png)][website]
2
2
 
3
- Faraday is an HTTP client lib that provides a common interface over many
4
- adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
5
- processing the request/response cycle.
6
-
7
- Faraday supports these adapters:
8
-
9
- * [Net::HTTP][net_http] _(default)_
10
- * [Net::HTTP::Persistent][persistent]
11
- * [Excon][]
12
- * [Typhoeus][]
13
- * [Patron][]
14
- * [EventMachine][]
15
- * [HTTPClient][]
16
-
17
- It also includes a Rack adapter for hitting loaded Rack applications through
18
- Rack::Test, and a Test adapter for stubbing requests by hand.
19
-
20
- ## Usage
21
-
22
- ```ruby
23
- conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
24
- faraday.request :url_encoded # form-encode POST params
25
- faraday.response :logger # log requests to STDOUT
26
- faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
27
- end
28
-
29
- ## GET ##
30
-
31
- response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
32
- response.body
33
-
34
- conn.get '/nigiri', { :name => 'Maguro' } # GET http://sushi.com/nigiri?name=Maguro
35
-
36
- conn.get do |req| # GET http://sushi.com/search?page=2&limit=100
37
- req.url '/search', :page => 2
38
- req.params['limit'] = 100
39
- end
40
-
41
- ## POST ##
42
-
43
- conn.post '/nigiri', { :name => 'Maguro' } # POST "name=maguro" to http://sushi.com/nigiri
44
-
45
- # post payload as JSON instead of "www-form-urlencoded" encoding:
46
- conn.post do |req|
47
- req.url '/nigiri'
48
- req.headers['Content-Type'] = 'application/json'
49
- req.body = '{ "name": "Unagi" }'
50
- end
51
-
52
- ## Per-request options ##
53
-
54
- conn.get do |req|
55
- req.url '/search'
56
- req.options.timeout = 5 # open/read timeout in seconds
57
- req.options.open_timeout = 2 # connection open timeout in seconds
58
- end
59
- ```
60
-
61
- If you don't need to set up anything, you can roll with just the default middleware
62
- stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)):
63
-
64
- ```ruby
65
- response = Faraday.get 'http://sushi.com/nigiri/sake.json'
66
- ```
67
-
68
- ### Changing how parameters are serialized
69
-
70
- Sometimes you need to send the same URL parameter multiple times with different
71
- values. This requires manually setting the parameter encoder and can be done on
72
- either per-connection or per-request basis.
73
-
74
- ```ruby
75
- # per-connection setting
76
- conn = Faraday.new :params_encoder => Faraday::FlatParamsEncoder
77
-
78
- conn.get do |req|
79
- # per-request setting:
80
- # req.options.params_encoder = my_encoder
81
- req.params['roll'] = ['california', 'philadelphia']
82
- end
83
- # GET 'http://sushi.com?roll=california&roll=philadelphia'
84
- ```
85
-
86
- The value of Faraday `params_encoder` can be any object that responds to:
87
-
88
- * `encode(hash) #=> String`
89
- * `decode(string) #=> Hash`
90
-
91
- The encoder will affect both how query strings are processed and how POST bodies
92
- get serialized. The default encoder is Faraday::NestedParamsEncoder.
93
-
94
- ## Advanced middleware usage
3
+ [![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
4
+ ![GitHub Actions CI](https://github.com/lostisland/faraday/workflows/CI/badge.svg)
5
+ [![Test Coverage](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/test_coverage)](https://codeclimate.com/github/lostisland/faraday/test_coverage)
6
+ [![Maintainability](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/maintainability)](https://codeclimate.com/github/lostisland/faraday/maintainability)
7
+ [![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
95
8
 
96
- The order in which middleware is stacked is important. Like with Rack, the
97
- first middleware on the list wraps all others, while the last middleware is the
98
- innermost one, so that must be the adapter.
99
9
 
100
- ```ruby
101
- Faraday.new(...) do |conn|
102
- # POST/PUT params encoders:
103
- conn.request :multipart
104
- conn.request :url_encoded
105
-
106
- conn.adapter :net_http
107
- end
108
- ```
109
-
110
- This request middleware setup affects POST/PUT requests in the following way:
111
-
112
- 1. `Request::Multipart` checks for files in the payload, otherwise leaves
113
- everything untouched;
114
- 2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
115
- already encoded or of another type
116
-
117
- Swapping middleware means giving the other priority. Specifying the
118
- "Content-Type" for the request is explicitly stating which middleware should
119
- process it.
120
-
121
- Examples:
122
-
123
- ```ruby
124
- # uploading a file:
125
- payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
126
-
127
- # "Multipart" middleware detects files and encodes with "multipart/form-data":
128
- conn.put '/profile', payload
129
- ```
130
-
131
- ## Writing middleware
132
-
133
- Middleware are classes that implement a `call` instance method. They hook into
134
- the request/response cycle.
135
-
136
- ```ruby
137
- def call(request_env)
138
- # do something with the request
139
- # request_env[:request_headers].merge!(...)
140
-
141
- @app.call(request_env).on_complete do |response_env|
142
- # do something with the response
143
- # response_env[:response_headers].merge!(...)
144
- end
145
- end
146
- ```
147
-
148
- It's important to do all processing of the response only in the `on_complete`
149
- block. This enables middleware to work in parallel mode where requests are
150
- asynchronous.
151
-
152
- The `env` is a hash with symbol keys that contains info about the request and,
153
- later, response. Some keys are:
154
-
155
- ```
156
- # request phase
157
- :method - :get, :post, ...
158
- :url - URI for the current request; also contains GET parameters
159
- :body - POST parameters for :post/:put requests
160
- :request_headers
161
-
162
- # response phase
163
- :status - HTTP response status code, such as 200
164
- :body - the response body
165
- :response_headers
166
- ```
167
-
168
- ## Using Faraday for testing
169
-
170
- ```ruby
171
- # It's possible to define stubbed request outside a test adapter block.
172
- stubs = Faraday::Adapter::Test::Stubs.new do |stub|
173
- stub.get('/tamago') { |env| [200, {}, 'egg'] }
174
- end
175
-
176
- # You can pass stubbed request to the test adapter or define them in a block
177
- # or a combination of the two.
178
- test = Faraday.new do |builder|
179
- builder.adapter :test, stubs do |stub|
180
- stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
181
- end
182
- end
183
-
184
- # It's also possible to stub additional requests after the connection has
185
- # been initialized. This is useful for testing.
186
- stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
187
-
188
- resp = test.get '/tamago'
189
- resp.body # => 'egg'
190
- resp = test.get '/ebi'
191
- resp.body # => 'shrimp'
192
- resp = test.get '/uni'
193
- resp.body # => 'urchin'
194
- resp = test.get '/else' #=> raises "no such stub" error
195
-
196
- # If you like, you can treat your stubs as mocks by verifying that all of
197
- # the stubbed calls were made. NOTE that this feature is still fairly
198
- # experimental: It will not verify the order or count of any stub, only that
199
- # it was called once during the course of the test.
200
- stubs.verify_stubbed_calls
201
- ```
10
+ Faraday is an HTTP client library that provides a common interface over many
11
+ adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
12
+ processing the request/response cycle.
202
13
 
203
- ## TODO
14
+ ## Getting Started
204
15
 
205
- * support streaming requests/responses
206
- * better stubbing API
16
+ The best starting point is the [Faraday Website][website], with its introduction and explanation.
17
+ Need more details? See the [Faraday API Documentation][apidoc] to see how it works internally.
207
18
 
208
19
  ## Supported Ruby versions
209
20
 
210
- This library aims to support and is [tested against][travis] the following Ruby
21
+ This library aims to support and is [tested against][actions] the following Ruby
211
22
  implementations:
212
23
 
213
- * Ruby 1.8.7+
214
- * [JRuby][] 1.7+
215
- * [Rubinius][] 2+
24
+ * Ruby 2.4+
216
25
 
217
26
  If something doesn't work on one of these Ruby versions, it's a bug.
218
27
 
219
28
  This library may inadvertently work (or seem to work) on other Ruby
220
- implementations, however support will only be provided for the versions listed
29
+ implementations and versions, however support will only be provided for the versions listed
221
30
  above.
222
31
 
223
32
  If you would like this library to support another Ruby version, you may
@@ -227,19 +36,20 @@ implementation, you will be responsible for providing patches in a timely
227
36
  fashion. If critical issues for a particular implementation exist at the time
228
37
  of a major release, support for that Ruby version may be dropped.
229
38
 
230
- ## Copyright
39
+ ## Contribute
40
+
41
+ Do you want to contribute to Faraday?
42
+ Open the issues page and check for the `help wanted` label!
43
+ But before you start coding, please read our [Contributing Guide][contributing]
231
44
 
232
- Copyright (c) 2009-2013 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
233
- See [LICENSE][] for details.
45
+ ## Copyright
46
+ &copy; 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
234
47
 
235
- [net_http]: http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
236
- [persistent]: https://github.com/drbrain/net-http-persistent
237
- [travis]: http://travis-ci.org/lostisland/faraday
238
- [excon]: https://github.com/geemus/excon#readme
239
- [typhoeus]: https://github.com/typhoeus/typhoeus#readme
240
- [patron]: http://toland.github.com/patron/
241
- [eventmachine]: https://github.com/igrigorik/em-http-request#readme
242
- [httpclient]: https://github.com/nahi/httpclient
48
+ [website]: https://lostisland.github.io/faraday
49
+ [faraday_team]: https://lostisland.github.io/faraday/team
50
+ [contributing]: https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md
51
+ [apidoc]: http://www.rubydoc.info/gems/faraday
52
+ [actions]: https://github.com/lostisland/faraday/actions
243
53
  [jruby]: http://jruby.org/
244
54
  [rubinius]: http://rubini.us/
245
55
  [license]: LICENSE.md
data/Rakefile ADDED
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'rspec/core/rake_task'
4
+
5
+ RSpec::Core::RakeTask.new(:spec)
6
+
7
+ task default: :spec
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Requires Ruby with rspec and faraday gems.
4
+ # rspec client_spec.rb
5
+
6
+ require 'faraday'
7
+ require 'json'
8
+
9
+ # Example API client
10
+ class Client
11
+ def initialize(conn)
12
+ @conn = conn
13
+ end
14
+
15
+ def sushi(jname)
16
+ res = @conn.get("/#{jname}")
17
+ data = JSON.parse(res.body)
18
+ data['name']
19
+ end
20
+ end
21
+
22
+ Rspec.describe Client do
23
+ let(:stubs) { Faraday::Adapter::Test::Stubs.new }
24
+ let(:conn) { Faraday.new { |b| b.adapter(:test, stubs) } }
25
+ let(:client) { Client.new(conn) }
26
+
27
+ it 'parses name' do
28
+ stubs.get('/ebi') do |env|
29
+ # optional: you can inspect the Faraday::Env
30
+ expect(env.url.path).to eq('/ebi')
31
+ [
32
+ 200,
33
+ { 'Content-Type': 'application/javascript' },
34
+ '{"name": "shrimp"}'
35
+ ]
36
+ end
37
+
38
+ # uncomment to trigger stubs.verify_stubbed_calls failure
39
+ # stubs.get('/unused') { [404, {}, ''] }
40
+
41
+ expect(client.sushi('ebi')).to eq('shrimp')
42
+ stubs.verify_stubbed_calls
43
+ end
44
+
45
+ it 'handles 404' do
46
+ stubs.get('/ebi') do
47
+ [
48
+ 404,
49
+ { 'Content-Type': 'application/javascript' },
50
+ '{}'
51
+ ]
52
+ end
53
+ expect(client.sushi('ebi')).to be_nil
54
+ stubs.verify_stubbed_calls
55
+ end
56
+
57
+ it 'handles exception' do
58
+ stubs.get('/ebi') do
59
+ raise Faraday::ConnectionFailed, nil
60
+ end
61
+
62
+ expect { client.sushi('ebi') }.to raise_error(Faraday::ConnectionFailed)
63
+ stubs.verify_stubbed_calls
64
+ end
65
+ end