faraday 0.9.2 → 0.17.6
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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +232 -0
- data/LICENSE.md +1 -1
- data/README.md +168 -18
- data/Rakefile +13 -0
- data/lib/faraday/adapter/em_http.rb +17 -11
- data/lib/faraday/adapter/em_http_ssl_patch.rb +1 -1
- data/lib/faraday/adapter/em_synchrony.rb +13 -7
- data/lib/faraday/adapter/excon.rb +12 -11
- data/lib/faraday/adapter/httpclient.rb +21 -10
- data/lib/faraday/adapter/net_http.rb +36 -13
- data/lib/faraday/adapter/net_http_persistent.rb +36 -17
- data/lib/faraday/adapter/patron.rb +36 -19
- data/lib/faraday/adapter/rack.rb +1 -1
- data/lib/faraday/adapter/test.rb +79 -28
- data/lib/faraday/adapter/typhoeus.rb +4 -115
- data/lib/faraday/adapter.rb +10 -1
- data/lib/faraday/autoload.rb +1 -1
- data/lib/faraday/connection.rb +64 -17
- data/lib/faraday/deprecate.rb +109 -0
- data/lib/faraday/error.rb +132 -27
- data/lib/faraday/options.rb +36 -22
- data/lib/faraday/parameters.rb +2 -1
- data/lib/faraday/rack_builder.rb +26 -2
- data/lib/faraday/request/authorization.rb +1 -2
- data/lib/faraday/request/multipart.rb +7 -2
- data/lib/faraday/request/retry.rb +77 -18
- data/lib/faraday/request.rb +24 -0
- data/lib/faraday/response/logger.rb +29 -8
- data/lib/faraday/response/raise_error.rb +7 -3
- data/lib/faraday/response.rb +7 -3
- data/lib/faraday/upload_io.rb +16 -6
- data/lib/faraday/utils.rb +19 -2
- data/lib/faraday.rb +15 -36
- data/spec/faraday/deprecate_spec.rb +147 -0
- data/spec/faraday/error_spec.rb +102 -0
- data/spec/faraday/response/raise_error_spec.rb +106 -0
- data/spec/spec_helper.rb +105 -0
- data/test/adapters/default_test.rb +14 -0
- data/test/adapters/em_http_test.rb +30 -0
- data/test/adapters/em_synchrony_test.rb +32 -0
- data/test/adapters/excon_test.rb +30 -0
- data/test/adapters/httpclient_test.rb +34 -0
- data/test/adapters/integration.rb +263 -0
- data/test/adapters/logger_test.rb +136 -0
- data/test/adapters/net_http_persistent_test.rb +114 -0
- data/test/adapters/net_http_test.rb +79 -0
- data/test/adapters/patron_test.rb +40 -0
- data/test/adapters/rack_test.rb +38 -0
- data/test/adapters/test_middleware_test.rb +157 -0
- data/test/adapters/typhoeus_test.rb +38 -0
- data/test/authentication_middleware_test.rb +65 -0
- data/test/composite_read_io_test.rb +109 -0
- data/test/connection_test.rb +738 -0
- data/test/env_test.rb +268 -0
- data/test/helper.rb +75 -0
- data/test/live_server.rb +67 -0
- data/test/middleware/instrumentation_test.rb +88 -0
- data/test/middleware/retry_test.rb +282 -0
- data/test/middleware_stack_test.rb +260 -0
- data/test/multibyte.txt +1 -0
- data/test/options_test.rb +333 -0
- data/test/parameters_test.rb +157 -0
- data/test/request_middleware_test.rb +126 -0
- data/test/response_middleware_test.rb +72 -0
- data/test/strawberry.rb +2 -0
- data/test/utils_test.rb +98 -0
- metadata +81 -63
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 56d15adebd24ca50e38ac12d74f518927ee757abe32ce2693aac8f6b3b2d5db6
|
4
|
+
data.tar.gz: 72247b6844e16989a3c186a95e226b8254da0dff82854922242add3535707a9f
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: '08df648fee5c02b6fd54d70615ee97ccc978d5a16471cbfc4790150189de39799e60bd67d45236645c79785062dc14aef36a0c516e847c7a43615e7147381aad'
|
7
|
+
data.tar.gz: de528b3a2c4a552f68cfb95814729018106146c5bc0861abfcbd45d4202036c9e7347f40dfe1703a27a939e1960e2019bae9293039a1550031a41124c27dfd7c
|
data/CHANGELOG.md
ADDED
@@ -0,0 +1,232 @@
|
|
1
|
+
# Faraday Changelog
|
2
|
+
|
3
|
+
## v0.17.3
|
4
|
+
|
5
|
+
Fixes:
|
6
|
+
|
7
|
+
* Reverts changes in error classes hierarchy. #1092 (@iMacTia)
|
8
|
+
* Fix Ruby 1.9 syntax errors and improve Error class testing #1094 (@BanzaiMan,
|
9
|
+
@mrexox, @technoweenie)
|
10
|
+
|
11
|
+
Misc:
|
12
|
+
|
13
|
+
* Stops using `&Proc.new` for block forwarding. #1083 (@olleolleolle)
|
14
|
+
* Update CI to test against ruby 2.0-2.7 #1087, #1099 (@iMacTia, @olleolleolle,
|
15
|
+
@technoweenie)
|
16
|
+
* require FARADAY_DEPRECATE=warn to show Faraday v1.0 deprecation warnings
|
17
|
+
#1098 (@technoweenie)
|
18
|
+
|
19
|
+
## v0.17.1
|
20
|
+
|
21
|
+
Final release before Faraday v1.0, with important fixes for Ruby 2.7.
|
22
|
+
|
23
|
+
Fixes:
|
24
|
+
|
25
|
+
* RaiseError response middleware raises exception if HTTP client returns a nil
|
26
|
+
status. #1042 (@jonnyom, @BobbyMcWho)
|
27
|
+
|
28
|
+
Misc:
|
29
|
+
|
30
|
+
* Fix Ruby 2.7 warnings (#1009)
|
31
|
+
* Add `Faraday::Deprecate` to warn about upcoming v1.0 changes. (#1054, #1059,
|
32
|
+
#1076, #1077)
|
33
|
+
* Add release notes up to current in CHANGELOG.md (#1066)
|
34
|
+
* Port minimal rspec suite from main branch to run backported tests. (#1058)
|
35
|
+
|
36
|
+
## v0.17.0
|
37
|
+
|
38
|
+
This release is the same as v0.15.4. It was pushed to cover up releases
|
39
|
+
v0.16.0-v0.16.2.
|
40
|
+
|
41
|
+
## v0.15.4
|
42
|
+
|
43
|
+
* Expose `pool_size` as a option for the NetHttpPersistent adapter (#834)
|
44
|
+
|
45
|
+
## v0.15.3
|
46
|
+
|
47
|
+
* Make Faraday::Request serialisable with Marshal. (#803)
|
48
|
+
* Add DEFAULT_EXCEPTIONS constant to Request::Retry (#814)
|
49
|
+
* Add support for Ruby 2.6 Net::HTTP write_timeout (#824)
|
50
|
+
|
51
|
+
## v0.15.2
|
52
|
+
|
53
|
+
* Prevents `Net::HTTP` adapters to retry request internally by setting `max_retries` to 0 if available (Ruby 2.5+). (#799)
|
54
|
+
* Fixes `NestedParamsEncoder` handling of empty array values (#801)
|
55
|
+
|
56
|
+
## v0.15.1
|
57
|
+
|
58
|
+
* NetHttpPersistent adapter better reuse of SSL connections (#793)
|
59
|
+
* Refactor: inline cached_connection (#797)
|
60
|
+
* Logger middleware: use $stdout instead of STDOUT (#794)
|
61
|
+
* Fix: do not memoize/reuse Patron session (#796)
|
62
|
+
|
63
|
+
Also in this release:
|
64
|
+
|
65
|
+
* Allow setting min/max ssl version for Net::HTTP (#792)
|
66
|
+
* Allow setting min/max ssl version for Excon (#795)
|
67
|
+
|
68
|
+
## v0.15.0
|
69
|
+
|
70
|
+
Features:
|
71
|
+
|
72
|
+
* Added retry block option to retry middleware. (#770)
|
73
|
+
* Retry middleware improvements (honour Retry-After header, retry statuses) (#773)
|
74
|
+
* Improve response logger middleware output (#784)
|
75
|
+
|
76
|
+
Fixes:
|
77
|
+
|
78
|
+
* Remove unused class error (#767)
|
79
|
+
* Fix minor typo in README (#760)
|
80
|
+
* Reuse persistent connections when using net-http-persistent (#778)
|
81
|
+
* Fix Retry middleware documentation (#781)
|
82
|
+
* Returns the http response when giving up on retrying by status (#783)
|
83
|
+
|
84
|
+
## v0.14.0
|
85
|
+
|
86
|
+
Features:
|
87
|
+
|
88
|
+
* Allow overriding env proxy (#754)
|
89
|
+
* Remove legacy Typhoeus adapter (#715)
|
90
|
+
* External Typhoeus Adapter Compatibility (#748)
|
91
|
+
* Warn about missing adapter when making a request (#743)
|
92
|
+
* Faraday::Adapter::Test stubs now support entire urls (with host) (#741)
|
93
|
+
|
94
|
+
Fixes:
|
95
|
+
|
96
|
+
* If proxy is manually provided, this takes priority over `find_proxy` (#724)
|
97
|
+
* Fixes the behaviour for Excon's open_timeout (not setting write_timeout anymore) (#731)
|
98
|
+
* Handle all connection timeout messages in Patron (#687)
|
99
|
+
|
100
|
+
## v0.13.1
|
101
|
+
|
102
|
+
* Fixes an incompatibility with Addressable::URI being used as uri_parser
|
103
|
+
|
104
|
+
## v0.13.0
|
105
|
+
|
106
|
+
Features:
|
107
|
+
|
108
|
+
* Dynamically reloads the proxy when performing a request on an absolute domain (#701)
|
109
|
+
* Adapter support for Net::HTTP::Persistent v3.0.0 (#619)
|
110
|
+
|
111
|
+
Fixes:
|
112
|
+
|
113
|
+
* Prefer #hostname over #host. (#714)
|
114
|
+
* Fixes an edge-case issue with response headers parsing (missing HTTP header) (#719)
|
115
|
+
|
116
|
+
## v0.12.2
|
117
|
+
|
118
|
+
* Parse headers from aggregated proxy requests/responses (#681)
|
119
|
+
* Guard against invalid middleware configuration with warning (#685)
|
120
|
+
* Do not use :insecure option by default in Patron (#691)
|
121
|
+
* Fixes an issue with HTTPClient not raising a `Faraday::ConnectionFailed` (#702)
|
122
|
+
* Fixes YAML serialization/deserialization for `Faraday::Utils::Headers` (#690)
|
123
|
+
* Fixes an issue with Options having a nil value (#694)
|
124
|
+
* Fixes an issue with Faraday.default_connection not using Faraday.default_connection_options (#698)
|
125
|
+
* Fixes an issue with Options.merge! and Faraday instrumentation middleware (#710)
|
126
|
+
|
127
|
+
## v0.12.1
|
128
|
+
|
129
|
+
* Fix an issue with Patron tests failing on jruby
|
130
|
+
* Fix an issue with new `rewind_files` feature that was causing an exception when the body was not an Hash
|
131
|
+
* Expose wrapped_exception in all client errors
|
132
|
+
* Add Authentication Section to the ReadMe
|
133
|
+
|
134
|
+
## v0.12.0.1
|
135
|
+
|
136
|
+
* Hotfix release to address an issue with TravisCI deploy on Rubygems
|
137
|
+
|
138
|
+
## v0.12.0
|
139
|
+
|
140
|
+
Features:
|
141
|
+
|
142
|
+
* Proxy feature now relies on Ruby `URI::Generic#find_proxy` and can use `no_proxy` ENV variable (not compatible with ruby < 2.0)
|
143
|
+
* Adds support for `context` request option to pass arbitrary information to middlewares
|
144
|
+
|
145
|
+
Fixes:
|
146
|
+
|
147
|
+
* Fix an issue with options that was causing new options to override defaults ones unexpectedly
|
148
|
+
* Rewind `UploadIO`s on retry to fix a compatibility issue
|
149
|
+
* Make multipart boundary unique
|
150
|
+
* Improvements in `README.md`
|
151
|
+
|
152
|
+
## v0.11.0
|
153
|
+
|
154
|
+
Features:
|
155
|
+
|
156
|
+
* Add `filter` method to Logger middleware
|
157
|
+
* Add support for Ruby2.4 and Minitest 6
|
158
|
+
* Introduce block syntax to customise the adapter
|
159
|
+
|
160
|
+
Fixes:
|
161
|
+
|
162
|
+
* Fix an issue that was allowing to override `default_connection_options` from a connection instance
|
163
|
+
* Fix a bug that was causing newline escape characters ("\n") to be used when building the Authorization header
|
164
|
+
|
165
|
+
## v0.10.1
|
166
|
+
|
167
|
+
- Fix an issue with HTTPClient adapter that was causing the SSL to be reset on every request
|
168
|
+
- Rescue `IOError` instead of specific subclass
|
169
|
+
- `Faraday::Utils::Headers` can now be successfully serialised in YAML
|
170
|
+
- Handle `default_connection_options` set with hash
|
171
|
+
|
172
|
+
## v0.10.0
|
173
|
+
|
174
|
+
Breaking changes:
|
175
|
+
- Drop support for Ruby 1.8
|
176
|
+
|
177
|
+
Features:
|
178
|
+
- Include wrapped exception/reponse in ClientErrors
|
179
|
+
- Add `response.reason_phrase`
|
180
|
+
- Provide option to selectively skip logging request/response headers
|
181
|
+
- Add regex support for pattern matching in `test` adapter
|
182
|
+
|
183
|
+
Fixes:
|
184
|
+
- Add `Faraday.respond_to?` to find methods managed by `method_missing`
|
185
|
+
- em-http: `request.host` instead of `connection.host` should be taken for SSL validations
|
186
|
+
- Allow `default_connection_options` to be merged when options are passed as url parameter
|
187
|
+
- Improve splitting key-value pairs in raw HTTP headers
|
188
|
+
|
189
|
+
## v0.9.2
|
190
|
+
|
191
|
+
Adapters:
|
192
|
+
- Enable gzip compression for httpclient
|
193
|
+
- Fixes default certificate store for httpclient not having default paths.
|
194
|
+
- Make excon adapter compatible with 0.44 excon version
|
195
|
+
- Add compatibility with Patron 0.4.20
|
196
|
+
- Determine default port numbers in Net::HTTP adapters (Addressable compatibility)
|
197
|
+
- em-http: wrap "connection closed by server" as ConnectionFailed type
|
198
|
+
- Wrap Errno::ETIMEDOUT in Faraday::Error::TimeoutError
|
199
|
+
|
200
|
+
Utils:
|
201
|
+
- Add Rack-compatible support for parsing `a[][b]=c` nested queries
|
202
|
+
- Encode nil values in queries different than empty strings. Before: `a=`; now: `a`.
|
203
|
+
- Have `Faraday::Utils::Headers#replace` clear internal key cache
|
204
|
+
- Dup the internal key cache when a Headers hash is copied
|
205
|
+
|
206
|
+
Env and middleware:
|
207
|
+
- Ensure `env` stored on middleware response has reference to the response
|
208
|
+
- Ensure that Response properties are initialized during `on_complete` (VCR compatibility)
|
209
|
+
- Copy request options in Faraday::Connection#dup
|
210
|
+
- Env custom members should be copied by Env.from(env)
|
211
|
+
- Honour per-request `request.options.params_encoder`
|
212
|
+
- Fix `interval_randomness` data type for Retry middleware
|
213
|
+
- Add maximum interval option for Retry middleware
|
214
|
+
|
215
|
+
## v0.9.1
|
216
|
+
|
217
|
+
* Refactor Net:HTTP adapter so that with_net_http_connection can be overridden to allow pooled connections. (@Ben-M)
|
218
|
+
* Add configurable methods that bypass `retry_if` in the Retry request middleware. (@mike-bourgeous)
|
219
|
+
|
220
|
+
## v0.9.0
|
221
|
+
|
222
|
+
* Add HTTPClient adapter (@hakanensari)
|
223
|
+
* Improve Retry handler (@mislav)
|
224
|
+
* Remove autoloading by default (@technoweenie)
|
225
|
+
* Improve internal docs (@technoweenie, @mislav)
|
226
|
+
* Respect user/password in http proxy string (@mislav)
|
227
|
+
* Adapter options are structs. Reinforces consistent options across adapters
|
228
|
+
(@technoweenie)
|
229
|
+
* Stop stripping trailing / off base URLs in a Faraday::Connection. (@technoweenie)
|
230
|
+
* Add a configurable URI parser. (@technoweenie)
|
231
|
+
* Remove need to manually autoload when using the authorization header helpers on `Faraday::Connection`. (@technoweenie)
|
232
|
+
* `Faraday::Adapter::Test` respects the `Faraday::RequestOptions#params_encoder` option. (@technoweenie)
|
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -1,31 +1,88 @@
|
|
1
1
|
# Faraday
|
2
2
|
|
3
|
+
[](https://rubygems.org/gems/faraday)
|
4
|
+
[](https://travis-ci.org/lostisland/faraday)
|
5
|
+
[](https://coveralls.io/github/lostisland/faraday?branch=master)
|
6
|
+
[](https://codeclimate.com/github/lostisland/faraday)
|
7
|
+
[](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
8
|
+
|
9
|
+
|
3
10
|
Faraday is an HTTP client lib that provides a common interface over many
|
4
11
|
adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
|
5
12
|
processing the request/response cycle.
|
6
13
|
|
7
|
-
Faraday supports these adapters:
|
14
|
+
Faraday supports these adapters out of the box:
|
8
15
|
|
9
16
|
* [Net::HTTP][net_http] _(default)_
|
10
17
|
* [Net::HTTP::Persistent][persistent]
|
11
18
|
* [Excon][]
|
12
|
-
* [Typhoeus][]
|
13
19
|
* [Patron][]
|
14
20
|
* [EventMachine][]
|
15
21
|
* [HTTPClient][]
|
16
22
|
|
23
|
+
Adapters are slowly being moved into their own gems, or bundled with HTTP clients:
|
24
|
+
|
25
|
+
* [Typhoeus][]
|
26
|
+
|
17
27
|
It also includes a Rack adapter for hitting loaded Rack applications through
|
18
28
|
Rack::Test, and a Test adapter for stubbing requests by hand.
|
19
29
|
|
30
|
+
## API documentation
|
31
|
+
|
32
|
+
Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday).
|
33
|
+
|
34
|
+
## Faraday 1.0
|
35
|
+
|
36
|
+
Faraday 1.0 will ship soon! Faraday 0.17 will be the last 0.x release, except for serious bugs or security issues.
|
37
|
+
Faraday 1.0 is a major release, but it will be mostly backwards-compatible with 0.x, so we strongly encourage you
|
38
|
+
to use it on your next projects and/or consider to upgrade your existing ones.
|
39
|
+
Upgrading is simple:
|
40
|
+
|
41
|
+
* Checkout the new code from [`master`](https://github.com/lostisland/faraday) and the new [Documentation Website](https://lostisland.github.io/faraday/).
|
42
|
+
* If you're upgrading an existing project, check the [UPGRADING](https://github.com/lostisland/faraday/blob/master/UPGRADING.md) file.
|
43
|
+
* You can also enable upgrade warnings on apps with Faraday 0.x if you run them with `FARADAY_DEPRECATE=warn` or `FARADAY_DEPRECATE=1` in ENV.
|
44
|
+
|
20
45
|
## Usage
|
21
46
|
|
47
|
+
### Basic Use
|
48
|
+
|
49
|
+
```ruby
|
50
|
+
response = Faraday.get 'http://sushi.com/nigiri/sake.json'
|
51
|
+
```
|
52
|
+
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
|
53
|
+
stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)).
|
54
|
+
|
55
|
+
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:
|
56
|
+
|
57
|
+
```ruby
|
58
|
+
conn = Faraday.new(:url => 'http://www.example.com')
|
59
|
+
response = conn.get '/users' # GET http://www.example.com/users'
|
60
|
+
```
|
61
|
+
|
62
|
+
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.
|
63
|
+
Since the default middleware stack uses url\_encoded middleware and default adapter, use them on building your own middleware stack.
|
64
|
+
|
22
65
|
```ruby
|
23
66
|
conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
|
24
67
|
faraday.request :url_encoded # form-encode POST params
|
25
|
-
faraday.response :logger # log requests to
|
68
|
+
faraday.response :logger # log requests to $stdout
|
26
69
|
faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
|
27
70
|
end
|
28
71
|
|
72
|
+
# Filter sensitive information from logs with a regex matcher
|
73
|
+
|
74
|
+
conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
|
75
|
+
faraday.request :url_encoded # form-encode POST params
|
76
|
+
faraday.response :logger do | logger |
|
77
|
+
logger.filter(/(api_key=)(\w+)/,'\1[REMOVED]')
|
78
|
+
end
|
79
|
+
faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
|
80
|
+
end
|
81
|
+
```
|
82
|
+
|
83
|
+
Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways:
|
84
|
+
|
85
|
+
```ruby
|
29
86
|
## GET ##
|
30
87
|
|
31
88
|
response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
|
@@ -41,7 +98,11 @@ end
|
|
41
98
|
## POST ##
|
42
99
|
|
43
100
|
conn.post '/nigiri', { :name => 'Maguro' } # POST "name=maguro" to http://sushi.com/nigiri
|
101
|
+
```
|
102
|
+
|
103
|
+
Some configuration options can be adjusted per request:
|
44
104
|
|
105
|
+
```ruby
|
45
106
|
# post payload as JSON instead of "www-form-urlencoded" encoding:
|
46
107
|
conn.post do |req|
|
47
108
|
req.url '/nigiri'
|
@@ -58,11 +119,18 @@ conn.get do |req|
|
|
58
119
|
end
|
59
120
|
```
|
60
121
|
|
61
|
-
|
62
|
-
stack and default adapter (see [Faraday::RackBuilder#initialize](https://github.com/lostisland/faraday/blob/master/lib/faraday/rack_builder.rb)):
|
122
|
+
And you can inject arbitrary data into the request using the `context` option:
|
63
123
|
|
64
124
|
```ruby
|
65
|
-
|
125
|
+
# Anything you inject using context option will be available in the env on all middlewares
|
126
|
+
|
127
|
+
conn.get do |req|
|
128
|
+
req.url '/search'
|
129
|
+
req.options.context = {
|
130
|
+
foo: 'foo',
|
131
|
+
bar: 'bar'
|
132
|
+
}
|
133
|
+
end
|
66
134
|
```
|
67
135
|
|
68
136
|
### Changing how parameters are serialized
|
@@ -73,7 +141,7 @@ either per-connection or per-request basis.
|
|
73
141
|
|
74
142
|
```ruby
|
75
143
|
# per-connection setting
|
76
|
-
conn = Faraday.new :params_encoder => Faraday::FlatParamsEncoder
|
144
|
+
conn = Faraday.new :request => { :params_encoder => Faraday::FlatParamsEncoder }
|
77
145
|
|
78
146
|
conn.get do |req|
|
79
147
|
# per-request setting:
|
@@ -91,6 +159,36 @@ The value of Faraday `params_encoder` can be any object that responds to:
|
|
91
159
|
The encoder will affect both how query strings are processed and how POST bodies
|
92
160
|
get serialized. The default encoder is Faraday::NestedParamsEncoder.
|
93
161
|
|
162
|
+
## Authentication
|
163
|
+
|
164
|
+
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.
|
165
|
+
|
166
|
+
```ruby
|
167
|
+
Faraday.new(...) do |conn|
|
168
|
+
conn.basic_auth('username', 'password')
|
169
|
+
end
|
170
|
+
|
171
|
+
Faraday.new(...) do |conn|
|
172
|
+
conn.token_auth('authentication-token')
|
173
|
+
end
|
174
|
+
```
|
175
|
+
|
176
|
+
## Proxy
|
177
|
+
|
178
|
+
Faraday will try to automatically infer the proxy settings from your system using `URI#find_proxy`.
|
179
|
+
This will retrieve them from environment variables such as http_proxy, ftp_proxy, no_proxy, etc.
|
180
|
+
If for any reason you want to disable this behaviour, you can do so by setting the global varibale `ignore_env_proxy`:
|
181
|
+
|
182
|
+
```ruby
|
183
|
+
Faraday.ignore_env_proxy = true
|
184
|
+
```
|
185
|
+
|
186
|
+
You can also specify a custom proxy when initializing the connection
|
187
|
+
|
188
|
+
```ruby
|
189
|
+
Faraday.new('http://www.example.com', :proxy => 'http://proxy.com')
|
190
|
+
```
|
191
|
+
|
94
192
|
## Advanced middleware usage
|
95
193
|
|
96
194
|
The order in which middleware is stacked is important. Like with Rack, the
|
@@ -102,7 +200,11 @@ Faraday.new(...) do |conn|
|
|
102
200
|
# POST/PUT params encoders:
|
103
201
|
conn.request :multipart
|
104
202
|
conn.request :url_encoded
|
203
|
+
|
204
|
+
# add custom middleware
|
205
|
+
conn.use MyMiddleware
|
105
206
|
|
207
|
+
# Last middleware must be the adapter:
|
106
208
|
conn.adapter :net_http
|
107
209
|
end
|
108
210
|
```
|
@@ -165,6 +267,53 @@ later, response. Some keys are:
|
|
165
267
|
:response_headers
|
166
268
|
```
|
167
269
|
|
270
|
+
## Ad-hoc adapters customization
|
271
|
+
|
272
|
+
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.
|
273
|
+
|
274
|
+
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.
|
275
|
+
|
276
|
+
### NetHttp
|
277
|
+
```ruby
|
278
|
+
conn = Faraday.new(...) do |f|
|
279
|
+
f.adapter :net_http do |http| # yields Net::HTTP
|
280
|
+
http.idle_timeout = 100
|
281
|
+
http.verify_callback = lambda do | preverify_ok, cert_store |
|
282
|
+
# do something here...
|
283
|
+
end
|
284
|
+
end
|
285
|
+
end
|
286
|
+
```
|
287
|
+
|
288
|
+
### NetHttpPersistent
|
289
|
+
```ruby
|
290
|
+
conn = Faraday.new(...) do |f|
|
291
|
+
f.adapter :net_http_persistent, pool_size: 5 do |http| # yields Net::HTTP::Persistent
|
292
|
+
http.idle_timeout = 100
|
293
|
+
http.retry_change_requests = true
|
294
|
+
end
|
295
|
+
end
|
296
|
+
```
|
297
|
+
|
298
|
+
### Patron
|
299
|
+
```ruby
|
300
|
+
conn = Faraday.new(...) do |f|
|
301
|
+
f.adapter :patron do |session| # yields Patron::Session
|
302
|
+
session.max_redirects = 10
|
303
|
+
end
|
304
|
+
end
|
305
|
+
```
|
306
|
+
|
307
|
+
### HTTPClient
|
308
|
+
```ruby
|
309
|
+
conn = Faraday.new(...) do |f|
|
310
|
+
f.adapter :httpclient do |client| # yields HTTPClient
|
311
|
+
client.keep_alive_timeout = 20
|
312
|
+
client.ssl_config.timeout = 25
|
313
|
+
end
|
314
|
+
end
|
315
|
+
```
|
316
|
+
|
168
317
|
## Using Faraday for testing
|
169
318
|
|
170
319
|
```ruby
|
@@ -200,17 +349,12 @@ resp = test.get '/else' #=> raises "no such stub" error
|
|
200
349
|
stubs.verify_stubbed_calls
|
201
350
|
```
|
202
351
|
|
203
|
-
## TODO
|
204
|
-
|
205
|
-
* support streaming requests/responses
|
206
|
-
* better stubbing API
|
207
|
-
|
208
352
|
## Supported Ruby versions
|
209
353
|
|
210
354
|
This library aims to support and is [tested against][travis] the following Ruby
|
211
355
|
implementations:
|
212
356
|
|
213
|
-
* Ruby 1.
|
357
|
+
* Ruby 1.9.3+
|
214
358
|
* [JRuby][] 1.7+
|
215
359
|
* [Rubinius][] 2+
|
216
360
|
|
@@ -227,19 +371,25 @@ implementation, you will be responsible for providing patches in a timely
|
|
227
371
|
fashion. If critical issues for a particular implementation exist at the time
|
228
372
|
of a major release, support for that Ruby version may be dropped.
|
229
373
|
|
374
|
+
## Contribute
|
375
|
+
|
376
|
+
Do you want to contribute to Faraday?
|
377
|
+
Open the issues page and check for the `help wanted` label!
|
378
|
+
But before you start coding, please read our [Contributing Guide](https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md)
|
379
|
+
|
230
380
|
## Copyright
|
231
381
|
|
232
|
-
Copyright (c) 2009-
|
382
|
+
Copyright (c) 2009-2017 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
|
233
383
|
See [LICENSE][] for details.
|
234
384
|
|
235
385
|
[net_http]: http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
|
236
386
|
[persistent]: https://github.com/drbrain/net-http-persistent
|
237
|
-
[travis]:
|
238
|
-
[excon]: https://github.com/
|
239
|
-
[
|
240
|
-
[patron]: http://toland.github.com/patron/
|
387
|
+
[travis]: https://travis-ci.org/lostisland/faraday
|
388
|
+
[excon]: https://github.com/excon/excon#readme
|
389
|
+
[patron]: http://toland.github.io/patron/
|
241
390
|
[eventmachine]: https://github.com/igrigorik/em-http-request#readme
|
242
391
|
[httpclient]: https://github.com/nahi/httpclient
|
392
|
+
[typhoeus]: https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
|
243
393
|
[jruby]: http://jruby.org/
|
244
394
|
[rubinius]: http://rubini.us/
|
245
395
|
[license]: LICENSE.md
|
data/Rakefile
ADDED
@@ -124,9 +124,9 @@ module Faraday
|
|
124
124
|
end
|
125
125
|
rescue EventMachine::Connectify::CONNECTError => err
|
126
126
|
if err.message.include?("Proxy Authentication Required")
|
127
|
-
raise
|
127
|
+
raise Faraday::ConnectionFailed, %{407 "Proxy Authentication Required "}
|
128
128
|
else
|
129
|
-
raise
|
129
|
+
raise Faraday::ConnectionFailed, err
|
130
130
|
end
|
131
131
|
rescue => err
|
132
132
|
if defined?(OpenSSL) && OpenSSL::SSL::SSLError === err
|
@@ -138,9 +138,11 @@ module Faraday
|
|
138
138
|
|
139
139
|
# TODO: reuse the connection to support pipelining
|
140
140
|
def perform_single_request(env)
|
141
|
-
req =
|
141
|
+
req = create_request(env)
|
142
142
|
req.setup_request(env[:method], request_config(env)).callback { |client|
|
143
|
-
|
143
|
+
status = client.response_header.status
|
144
|
+
reason = client.response_header.http_reason
|
145
|
+
save_response(env, status, client.response, nil, reason) do |resp_headers|
|
144
146
|
client.response_header.each do |name, value|
|
145
147
|
resp_headers[name.to_sym] = value
|
146
148
|
end
|
@@ -148,20 +150,24 @@ module Faraday
|
|
148
150
|
}
|
149
151
|
end
|
150
152
|
|
153
|
+
def create_request(env)
|
154
|
+
EventMachine::HttpRequest.new(env[:url], connection_config(env).merge(@connection_options))
|
155
|
+
end
|
156
|
+
|
151
157
|
def error_message(client)
|
152
158
|
client.error or "request failed"
|
153
159
|
end
|
154
160
|
|
155
161
|
def raise_error(msg)
|
156
|
-
errklass = Faraday::
|
162
|
+
errklass = Faraday::ClientError
|
157
163
|
if msg == Errno::ETIMEDOUT
|
158
|
-
errklass = Faraday::
|
164
|
+
errklass = Faraday::TimeoutError
|
159
165
|
msg = "request timed out"
|
160
166
|
elsif msg == Errno::ECONNREFUSED
|
161
|
-
errklass = Faraday::
|
167
|
+
errklass = Faraday::ConnectionFailed
|
162
168
|
msg = "connection refused"
|
163
169
|
elsif msg == "connection closed by server"
|
164
|
-
errklass = Faraday::
|
170
|
+
errklass = Faraday::ConnectionFailed
|
165
171
|
end
|
166
172
|
raise errklass, msg
|
167
173
|
end
|
@@ -187,11 +193,11 @@ module Faraday
|
|
187
193
|
|
188
194
|
def running?() @running end
|
189
195
|
|
190
|
-
def add
|
196
|
+
def add(&block)
|
191
197
|
if running?
|
192
198
|
perform_request { yield }
|
193
199
|
else
|
194
|
-
@registered_procs <<
|
200
|
+
@registered_procs << block
|
195
201
|
end
|
196
202
|
@num_registered += 1
|
197
203
|
end
|
@@ -205,7 +211,7 @@ module Faraday
|
|
205
211
|
end
|
206
212
|
end
|
207
213
|
if @errors.size > 0
|
208
|
-
raise Faraday::
|
214
|
+
raise Faraday::ClientError, @errors.first || "connection failed"
|
209
215
|
end
|
210
216
|
end
|
211
217
|
ensure
|
@@ -19,7 +19,7 @@ module Faraday
|
|
19
19
|
|
20
20
|
def call(env)
|
21
21
|
super
|
22
|
-
request =
|
22
|
+
request = create_request(env)
|
23
23
|
|
24
24
|
http_method = env[:method].to_s.downcase.to_sym
|
25
25
|
|
@@ -54,7 +54,9 @@ module Faraday
|
|
54
54
|
|
55
55
|
raise client.error if client.error
|
56
56
|
|
57
|
-
|
57
|
+
status = client.response_header.status
|
58
|
+
reason = client.response_header.http_reason
|
59
|
+
save_response(env, status, client.response, nil, reason) do |resp_headers|
|
58
60
|
client.response_header.each do |name, value|
|
59
61
|
resp_headers[name.to_sym] = value
|
60
62
|
end
|
@@ -63,18 +65,18 @@ module Faraday
|
|
63
65
|
|
64
66
|
@app.call env
|
65
67
|
rescue Errno::ECONNREFUSED
|
66
|
-
raise
|
68
|
+
raise Faraday::ConnectionFailed, $!
|
67
69
|
rescue EventMachine::Connectify::CONNECTError => err
|
68
70
|
if err.message.include?("Proxy Authentication Required")
|
69
|
-
raise
|
71
|
+
raise Faraday::ConnectionFailed, %{407 "Proxy Authentication Required "}
|
70
72
|
else
|
71
|
-
raise
|
73
|
+
raise Faraday::ConnectionFailed, err
|
72
74
|
end
|
73
75
|
rescue Errno::ETIMEDOUT => err
|
74
|
-
raise
|
76
|
+
raise Faraday::TimeoutError, err
|
75
77
|
rescue RuntimeError => err
|
76
78
|
if err.message == "connection closed by server"
|
77
|
-
raise
|
79
|
+
raise Faraday::ConnectionFailed, err
|
78
80
|
else
|
79
81
|
raise
|
80
82
|
end
|
@@ -85,6 +87,10 @@ module Faraday
|
|
85
87
|
raise
|
86
88
|
end
|
87
89
|
end
|
90
|
+
|
91
|
+
def create_request(env)
|
92
|
+
EventMachine::HttpRequest.new(Utils::URI(env[:url].to_s), connection_config(env).merge(@connection_options))
|
93
|
+
end
|
88
94
|
end
|
89
95
|
end
|
90
96
|
end
|