faraday 0.12.2 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (103) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +276 -0
  3. data/LICENSE.md +1 -1
  4. data/README.md +23 -325
  5. data/Rakefile +7 -0
  6. data/UPGRADING.md +55 -0
  7. data/examples/client_spec.rb +65 -0
  8. data/examples/client_test.rb +79 -0
  9. data/lib/faraday/adapter/em_http.rb +143 -101
  10. data/lib/faraday/adapter/em_http_ssl_patch.rb +24 -18
  11. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +18 -15
  12. data/lib/faraday/adapter/em_synchrony.rb +104 -60
  13. data/lib/faraday/adapter/excon.rb +98 -54
  14. data/lib/faraday/adapter/httpclient.rb +82 -59
  15. data/lib/faraday/adapter/net_http.rb +126 -52
  16. data/lib/faraday/adapter/net_http_persistent.rb +68 -27
  17. data/lib/faraday/adapter/patron.rb +86 -37
  18. data/lib/faraday/adapter/rack.rb +30 -13
  19. data/lib/faraday/adapter/test.rb +103 -62
  20. data/lib/faraday/adapter/typhoeus.rb +7 -115
  21. data/lib/faraday/adapter.rb +84 -22
  22. data/lib/faraday/adapter_registry.rb +28 -0
  23. data/lib/faraday/autoload.rb +47 -36
  24. data/lib/faraday/connection.rb +336 -177
  25. data/lib/faraday/dependency_loader.rb +37 -0
  26. data/lib/faraday/encoders/flat_params_encoder.rb +98 -0
  27. data/lib/faraday/encoders/nested_params_encoder.rb +171 -0
  28. data/lib/faraday/error.rb +106 -37
  29. data/lib/faraday/file_part.rb +128 -0
  30. data/lib/faraday/logging/formatter.rb +105 -0
  31. data/lib/faraday/middleware.rb +12 -28
  32. data/lib/faraday/middleware_registry.rb +129 -0
  33. data/lib/faraday/options/connection_options.rb +22 -0
  34. data/lib/faraday/options/env.rb +181 -0
  35. data/lib/faraday/options/proxy_options.rb +28 -0
  36. data/lib/faraday/options/request_options.rb +22 -0
  37. data/lib/faraday/options/ssl_options.rb +59 -0
  38. data/lib/faraday/options.rb +35 -185
  39. data/lib/faraday/param_part.rb +53 -0
  40. data/lib/faraday/parameters.rb +4 -196
  41. data/lib/faraday/rack_builder.rb +67 -54
  42. data/lib/faraday/request/authorization.rb +42 -30
  43. data/lib/faraday/request/basic_authentication.rb +14 -7
  44. data/lib/faraday/request/instrumentation.rb +45 -27
  45. data/lib/faraday/request/multipart.rb +79 -48
  46. data/lib/faraday/request/retry.rb +209 -134
  47. data/lib/faraday/request/token_authentication.rb +15 -10
  48. data/lib/faraday/request/url_encoded.rb +41 -23
  49. data/lib/faraday/request.rb +82 -30
  50. data/lib/faraday/response/logger.rb +22 -69
  51. data/lib/faraday/response/raise_error.rb +38 -14
  52. data/lib/faraday/response.rb +23 -16
  53. data/lib/faraday/utils/headers.rb +139 -0
  54. data/lib/faraday/utils/params_hash.rb +61 -0
  55. data/lib/faraday/utils.rb +28 -245
  56. data/lib/faraday.rb +96 -174
  57. data/spec/external_adapters/faraday_specs_setup.rb +14 -0
  58. data/spec/faraday/adapter/em_http_spec.rb +47 -0
  59. data/spec/faraday/adapter/em_synchrony_spec.rb +16 -0
  60. data/spec/faraday/adapter/excon_spec.rb +49 -0
  61. data/spec/faraday/adapter/httpclient_spec.rb +73 -0
  62. data/spec/faraday/adapter/net_http_persistent_spec.rb +57 -0
  63. data/spec/faraday/adapter/net_http_spec.rb +64 -0
  64. data/spec/faraday/adapter/patron_spec.rb +18 -0
  65. data/spec/faraday/adapter/rack_spec.rb +8 -0
  66. data/spec/faraday/adapter/typhoeus_spec.rb +7 -0
  67. data/spec/faraday/adapter_registry_spec.rb +28 -0
  68. data/spec/faraday/adapter_spec.rb +55 -0
  69. data/spec/faraday/composite_read_io_spec.rb +80 -0
  70. data/spec/faraday/connection_spec.rb +691 -0
  71. data/spec/faraday/error_spec.rb +45 -0
  72. data/spec/faraday/middleware_spec.rb +26 -0
  73. data/spec/faraday/options/env_spec.rb +70 -0
  74. data/spec/faraday/options/options_spec.rb +297 -0
  75. data/spec/faraday/options/proxy_options_spec.rb +37 -0
  76. data/spec/faraday/options/request_options_spec.rb +19 -0
  77. data/spec/faraday/params_encoders/flat_spec.rb +34 -0
  78. data/spec/faraday/params_encoders/nested_spec.rb +134 -0
  79. data/spec/faraday/rack_builder_spec.rb +196 -0
  80. data/spec/faraday/request/authorization_spec.rb +88 -0
  81. data/spec/faraday/request/instrumentation_spec.rb +76 -0
  82. data/spec/faraday/request/multipart_spec.rb +274 -0
  83. data/spec/faraday/request/retry_spec.rb +242 -0
  84. data/spec/faraday/request/url_encoded_spec.rb +70 -0
  85. data/spec/faraday/request_spec.rb +109 -0
  86. data/spec/faraday/response/logger_spec.rb +220 -0
  87. data/spec/faraday/response/middleware_spec.rb +52 -0
  88. data/spec/faraday/response/raise_error_spec.rb +106 -0
  89. data/spec/faraday/response_spec.rb +75 -0
  90. data/spec/faraday/utils/headers_spec.rb +82 -0
  91. data/spec/faraday/utils_spec.rb +56 -0
  92. data/spec/faraday_spec.rb +37 -0
  93. data/spec/spec_helper.rb +132 -0
  94. data/spec/support/disabling_stub.rb +14 -0
  95. data/spec/support/fake_safe_buffer.rb +15 -0
  96. data/spec/support/helper_methods.rb +133 -0
  97. data/spec/support/shared_examples/adapter.rb +104 -0
  98. data/spec/support/shared_examples/params_encoder.rb +18 -0
  99. data/spec/support/shared_examples/request_method.rb +234 -0
  100. data/spec/support/streaming_response_checker.rb +35 -0
  101. data/spec/support/webmock_rack_app.rb +68 -0
  102. metadata +78 -9
  103. data/lib/faraday/upload_io.rb +0 -67
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 515b1bc445a69d6ccdbb95b042750cd08962053a
4
- data.tar.gz: 504c63a2fb5c1bb6eec8b8cf9d930bd966984be2
2
+ SHA256:
3
+ metadata.gz: 9d3d650c5d465a0862cddd7ab2ed27fbfb4a6e5f2cfcbb54ba753bcc1ce9e40e
4
+ data.tar.gz: 953336deeb3dd2e0228368209bdffc7815b376772269c439e21374bc22b70484
5
5
  SHA512:
6
- metadata.gz: 5da384774bb02aae523a55d2f383ae4f0804757eabd1a398eca2998f6c6279391cb48c39e99d7948d63b4a71953ef98e31eb7e5dad57af5b615c9af007e8e870
7
- data.tar.gz: 63f74afdb08b2232af31ceb76309466f30a3fc4e4d9edbb2e67d4ecac94e432591edc0932fb32ad3945af261b49c7fc6663e06bc8fbfef1f24a9ce60418cc76a
6
+ metadata.gz: b80c084a8714d995dec61c918891a63720dbcdddf2eb3ecb7106f40a03bb341c4f03ffe976365c5450b2dcffd0b1f52c1cd4320ea24591dfaef7d5fdbbe12562
7
+ data.tar.gz: 67f8134fae885d3bb2e621afa701d6d535409bbb0141ad699f4d290059d61bf856915f622e214251f05e8b893a69bf68439118074712a22e75e3705b249dbb85
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-2017 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,336 +1,32 @@
1
- # Faraday
1
+ # ![Faraday](./docs/assets/img/repo-card-slim.png)
2
2
 
3
3
  [![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
4
- [![Build Status](https://travis-ci.org/lostisland/faraday.svg)](https://travis-ci.org/lostisland/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)
5
7
  [![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
6
8
 
7
9
 
8
- Faraday is an HTTP client lib that provides a common interface over many
10
+ Faraday is an HTTP client library that provides a common interface over many
9
11
  adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
10
12
  processing the request/response cycle.
11
13
 
12
- Faraday supports these adapters:
14
+ ## Getting Started
13
15
 
14
- * [Net::HTTP][net_http] _(default)_
15
- * [Net::HTTP::Persistent][persistent]
16
- * [Excon][]
17
- * [Patron][]
18
- * [EventMachine][]
19
- * [HTTPClient][]
20
-
21
- It also includes a Rack adapter for hitting loaded Rack applications through
22
- Rack::Test, and a Test adapter for stubbing requests by hand.
23
-
24
- ## API documentation
25
-
26
- Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday).
27
-
28
- ## Usage
29
-
30
- ### Basic Use
31
-
32
- ```ruby
33
- response = Faraday.get 'http://sushi.com/nigiri/sake.json'
34
- ```
35
- A simple `get` request can be performed by using the syntax described above. This works if you don't need to set up anything; you can roll with just the default middleware
36
- stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)).
37
-
38
- A more flexible way to use Faraday is to start with a Connection object. If you want to keep the same defaults, you can use this syntax:
39
-
40
- ```ruby
41
- conn = Faraday.new(:url => 'http://www.example.com')
42
- response = conn.get '/users' # GET http://www.example.com/users'
43
- ```
44
-
45
- Connections can also take an options hash as a parameter or be configured by using a block. Checkout the section called [Advanced middleware usage](#advanced-middleware-usage) for more details about how to use this block for configurations.
46
- Since the default middleware stack uses url\_encoded middleware and default adapter, use them on building your own middleware stack.
47
-
48
- ```ruby
49
- conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
50
- faraday.request :url_encoded # form-encode POST params
51
- faraday.response :logger # log requests to STDOUT
52
- faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
53
- end
54
-
55
- # Filter sensitive information from logs with a regex matcher
56
-
57
- conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
58
- faraday.request :url_encoded # form-encode POST params
59
- faraday.response :logger do | logger |
60
- logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
61
- end
62
- faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
63
- end
64
- ```
65
-
66
- Once you have the connection object, use it to make HTTP requests. You can pass paramters to it in a few different ways:
67
-
68
- ```ruby
69
- ## GET ##
70
-
71
- response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
72
- response.body
73
-
74
- conn.get '/nigiri', { :name => 'Maguro' } # GET http://sushi.com/nigiri?name=Maguro
75
-
76
- conn.get do |req| # GET http://sushi.com/search?page=2&limit=100
77
- req.url '/search', :page => 2
78
- req.params['limit'] = 100
79
- end
80
-
81
- ## POST ##
82
-
83
- conn.post '/nigiri', { :name => 'Maguro' } # POST "name=maguro" to http://sushi.com/nigiri
84
- ```
85
-
86
- Some configuration options can be adjusted per request:
87
-
88
- ```ruby
89
- # post payload as JSON instead of "www-form-urlencoded" encoding:
90
- conn.post do |req|
91
- req.url '/nigiri'
92
- req.headers['Content-Type'] = 'application/json'
93
- req.body = '{ "name": "Unagi" }'
94
- end
95
-
96
- ## Per-request options ##
97
-
98
- conn.get do |req|
99
- req.url '/search'
100
- req.options.timeout = 5 # open/read timeout in seconds
101
- req.options.open_timeout = 2 # connection open timeout in seconds
102
- end
103
- ```
104
-
105
- And you can inject arbitrary data into the request using the `context` option:
106
-
107
- ```ruby
108
- # Anything you inject using context option will be available in the env on all middlewares
109
-
110
- conn.get do |req|
111
- req.url '/search'
112
- req.options.context = {
113
- foo: 'foo',
114
- bar: 'bar'
115
- }
116
- end
117
- ```
118
-
119
- ### Changing how parameters are serialized
120
-
121
- Sometimes you need to send the same URL parameter multiple times with different
122
- values. This requires manually setting the parameter encoder and can be done on
123
- either per-connection or per-request basis.
124
-
125
- ```ruby
126
- # per-connection setting
127
- conn = Faraday.new :request => { :params_encoder => Faraday::FlatParamsEncoder }
128
-
129
- conn.get do |req|
130
- # per-request setting:
131
- # req.options.params_encoder = my_encoder
132
- req.params['roll'] = ['california', 'philadelphia']
133
- end
134
- # GET 'http://sushi.com?roll=california&roll=philadelphia'
135
- ```
136
-
137
- The value of Faraday `params_encoder` can be any object that responds to:
138
-
139
- * `encode(hash) #=> String`
140
- * `decode(string) #=> Hash`
141
-
142
- The encoder will affect both how query strings are processed and how POST bodies
143
- get serialized. The default encoder is Faraday::NestedParamsEncoder.
144
-
145
- ## Authentication
146
-
147
- Basic and Token authentication are handled by Faraday::Request::BasicAuthentication and Faraday::Request::TokenAuthentication respectively. These can be added as middleware manually or through the helper methods.
148
-
149
- ```ruby
150
- Faraday.new(...) do |conn|
151
- conn.basic_auth('username', 'password')
152
- end
153
-
154
- Faraday.new(...) do |conn|
155
- conn.token_auth('authentication-token')
156
- end
157
- ```
158
-
159
- ## Advanced middleware usage
160
-
161
- The order in which middleware is stacked is important. Like with Rack, the
162
- first middleware on the list wraps all others, while the last middleware is the
163
- innermost one, so that must be the adapter.
164
-
165
- ```ruby
166
- Faraday.new(...) do |conn|
167
- # POST/PUT params encoders:
168
- conn.request :multipart
169
- conn.request :url_encoded
170
-
171
- # Last middleware must be the adapter:
172
- conn.adapter :net_http
173
- end
174
- ```
175
-
176
- This request middleware setup affects POST/PUT requests in the following way:
177
-
178
- 1. `Request::Multipart` checks for files in the payload, otherwise leaves
179
- everything untouched;
180
- 2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
181
- already encoded or of another type
182
-
183
- Swapping middleware means giving the other priority. Specifying the
184
- "Content-Type" for the request is explicitly stating which middleware should
185
- process it.
186
-
187
- Examples:
188
-
189
- ```ruby
190
- # uploading a file:
191
- payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
192
-
193
- # "Multipart" middleware detects files and encodes with "multipart/form-data":
194
- conn.put '/profile', payload
195
- ```
196
-
197
- ## Writing middleware
198
-
199
- Middleware are classes that implement a `call` instance method. They hook into
200
- the request/response cycle.
201
-
202
- ```ruby
203
- def call(request_env)
204
- # do something with the request
205
- # request_env[:request_headers].merge!(...)
206
-
207
- @app.call(request_env).on_complete do |response_env|
208
- # do something with the response
209
- # response_env[:response_headers].merge!(...)
210
- end
211
- end
212
- ```
213
-
214
- It's important to do all processing of the response only in the `on_complete`
215
- block. This enables middleware to work in parallel mode where requests are
216
- asynchronous.
217
-
218
- The `env` is a hash with symbol keys that contains info about the request and,
219
- later, response. Some keys are:
220
-
221
- ```
222
- # request phase
223
- :method - :get, :post, ...
224
- :url - URI for the current request; also contains GET parameters
225
- :body - POST parameters for :post/:put requests
226
- :request_headers
227
-
228
- # response phase
229
- :status - HTTP response status code, such as 200
230
- :body - the response body
231
- :response_headers
232
- ```
233
-
234
- ## Ad-hoc adapters customization
235
-
236
- Faraday is intended to be a generic interface between your code and the adapter. However, sometimes you need to access a feature specific to one of the adapters that is not covered in Faraday's interface.
237
-
238
- When that happens, you can pass a block when specifying the adapter to customize it. The block parameter will change based on the adapter you're using. See below for some examples.
239
-
240
- ### NetHttp
241
- ```ruby
242
- conn = Faraday.new(...) do |f|
243
- f.adapter :net_http do |http| # yields Net::HTTP
244
- http.idle_timeout = 100
245
- http.verify_callback = lambda do | preverify_ok, cert_store |
246
- # do something here...
247
- end
248
- end
249
- end
250
- ```
251
-
252
- ### NetHttpPersistent
253
- ```ruby
254
- conn = Faraday.new(...) do |f|
255
- f.adapter :net_http_persistent do |http| # yields Net::HTTP::Persistent
256
- http.idle_timeout = 100
257
- http.retry_change_requests = true
258
- end
259
- end
260
- ```
261
-
262
- ### Patron
263
- ```ruby
264
- conn = Faraday.new(...) do |f|
265
- f.adapter :patron do |session| # yields Patron::Session
266
- session.max_redirects = 10
267
- end
268
- end
269
- ```
270
-
271
- ### HTTPClient
272
- ```ruby
273
- conn = Faraday.new(...) do |f|
274
- f.adapter :httpclient do |client| # yields HTTPClient
275
- client.keep_alive_timeout = 20
276
- client.ssl_config.timeout = 25
277
- end
278
- end
279
- ```
280
-
281
- ## Using Faraday for testing
282
-
283
- ```ruby
284
- # It's possible to define stubbed request outside a test adapter block.
285
- stubs = Faraday::Adapter::Test::Stubs.new do |stub|
286
- stub.get('/tamago') { |env| [200, {}, 'egg'] }
287
- end
288
-
289
- # You can pass stubbed request to the test adapter or define them in a block
290
- # or a combination of the two.
291
- test = Faraday.new do |builder|
292
- builder.adapter :test, stubs do |stub|
293
- stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
294
- end
295
- end
296
-
297
- # It's also possible to stub additional requests after the connection has
298
- # been initialized. This is useful for testing.
299
- stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
300
-
301
- resp = test.get '/tamago'
302
- resp.body # => 'egg'
303
- resp = test.get '/ebi'
304
- resp.body # => 'shrimp'
305
- resp = test.get '/uni'
306
- resp.body # => 'urchin'
307
- resp = test.get '/else' #=> raises "no such stub" error
308
-
309
- # If you like, you can treat your stubs as mocks by verifying that all of
310
- # the stubbed calls were made. NOTE that this feature is still fairly
311
- # experimental: It will not verify the order or count of any stub, only that
312
- # it was called once during the course of the test.
313
- stubs.verify_stubbed_calls
314
- ```
315
-
316
- ## TODO
317
-
318
- * support streaming requests/responses
319
- * 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.
320
18
 
321
19
  ## Supported Ruby versions
322
20
 
323
- 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
324
22
  implementations:
325
23
 
326
- * Ruby 1.9.3+
327
- * [JRuby][] 1.7+
328
- * [Rubinius][] 2+
24
+ * Ruby 2.4+
329
25
 
330
26
  If something doesn't work on one of these Ruby versions, it's a bug.
331
27
 
332
28
  This library may inadvertently work (or seem to work) on other Ruby
333
- 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
334
30
  above.
335
31
 
336
32
  If you would like this library to support another Ruby version, you may
@@ -340,18 +36,20 @@ implementation, you will be responsible for providing patches in a timely
340
36
  fashion. If critical issues for a particular implementation exist at the time
341
37
  of a major release, support for that Ruby version may be dropped.
342
38
 
343
- ## Copyright
39
+ ## Contribute
344
40
 
345
- Copyright (c) 2009-2017 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
346
- See [LICENSE][] for details.
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]
44
+
45
+ ## Copyright
46
+ &copy; 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
347
47
 
348
- [net_http]: http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
349
- [persistent]: https://github.com/drbrain/net-http-persistent
350
- [travis]: https://travis-ci.org/lostisland/faraday
351
- [excon]: https://github.com/excon/excon#readme
352
- [patron]: http://toland.github.io/patron/
353
- [eventmachine]: https://github.com/igrigorik/em-http-request#readme
354
- [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
355
53
  [jruby]: http://jruby.org/
356
54
  [rubinius]: http://rubini.us/
357
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