faraday 0.9.2 → 0.17.6
Sign up to get free protection for your applications and to get access to all the features.
- 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
|
+
[![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
|
4
|
+
[![Build Status](https://travis-ci.org/lostisland/faraday.svg?branch=master)](https://travis-ci.org/lostisland/faraday)
|
5
|
+
[![Coverage Status](https://coveralls.io/repos/github/lostisland/faraday/badge.svg?branch=master)](https://coveralls.io/github/lostisland/faraday?branch=master)
|
6
|
+
[![Code Climate](https://codeclimate.com/github/lostisland/faraday/badges/gpa.svg)](https://codeclimate.com/github/lostisland/faraday)
|
7
|
+
[![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](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
|