faraday 0.17.3 → 1.0.1
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 +4 -4
- data/CHANGELOG.md +52 -8
- data/LICENSE.md +1 -1
- data/README.md +18 -358
- data/Rakefile +1 -7
- data/examples/client_spec.rb +65 -0
- data/examples/client_test.rb +79 -0
- data/lib/faraday.rb +94 -175
- data/lib/faraday/adapter.rb +82 -22
- data/lib/faraday/adapter/em_http.rb +142 -99
- data/lib/faraday/adapter/em_http_ssl_patch.rb +24 -18
- data/lib/faraday/adapter/em_synchrony.rb +104 -60
- data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +18 -15
- data/lib/faraday/adapter/excon.rb +98 -56
- data/lib/faraday/adapter/httpclient.rb +83 -59
- data/lib/faraday/adapter/net_http.rb +130 -63
- data/lib/faraday/adapter/net_http_persistent.rb +50 -27
- data/lib/faraday/adapter/patron.rb +80 -43
- data/lib/faraday/adapter/rack.rb +30 -13
- data/lib/faraday/adapter/test.rb +86 -53
- data/lib/faraday/adapter/typhoeus.rb +4 -1
- data/lib/faraday/adapter_registry.rb +30 -0
- data/lib/faraday/autoload.rb +47 -36
- data/lib/faraday/connection.rb +312 -182
- data/lib/faraday/dependency_loader.rb +37 -0
- data/lib/faraday/encoders/flat_params_encoder.rb +98 -0
- data/lib/faraday/encoders/nested_params_encoder.rb +171 -0
- data/lib/faraday/error.rb +9 -35
- data/lib/faraday/file_part.rb +128 -0
- data/lib/faraday/logging/formatter.rb +105 -0
- data/lib/faraday/middleware.rb +12 -28
- data/lib/faraday/middleware_registry.rb +129 -0
- data/lib/faraday/options.rb +32 -183
- data/lib/faraday/options/connection_options.rb +22 -0
- data/lib/faraday/options/env.rb +181 -0
- data/lib/faraday/options/proxy_options.rb +28 -0
- data/lib/faraday/options/request_options.rb +22 -0
- data/lib/faraday/options/ssl_options.rb +59 -0
- data/lib/faraday/param_part.rb +53 -0
- data/lib/faraday/parameters.rb +4 -197
- data/lib/faraday/rack_builder.rb +66 -55
- data/lib/faraday/request.rb +68 -36
- data/lib/faraday/request/authorization.rb +44 -30
- data/lib/faraday/request/basic_authentication.rb +14 -7
- data/lib/faraday/request/instrumentation.rb +45 -27
- data/lib/faraday/request/multipart.rb +79 -48
- data/lib/faraday/request/retry.rb +197 -171
- data/lib/faraday/request/token_authentication.rb +15 -10
- data/lib/faraday/request/url_encoded.rb +43 -23
- data/lib/faraday/response.rb +24 -14
- data/lib/faraday/response/logger.rb +22 -69
- data/lib/faraday/response/raise_error.rb +38 -18
- data/lib/faraday/utils.rb +36 -245
- data/lib/faraday/utils/headers.rb +139 -0
- data/lib/faraday/utils/params_hash.rb +61 -0
- data/spec/external_adapters/faraday_specs_setup.rb +14 -0
- data/spec/faraday/adapter/em_http_spec.rb +47 -0
- data/spec/faraday/adapter/em_synchrony_spec.rb +16 -0
- data/spec/faraday/adapter/excon_spec.rb +49 -0
- data/spec/faraday/adapter/httpclient_spec.rb +73 -0
- data/spec/faraday/adapter/net_http_persistent_spec.rb +57 -0
- data/spec/faraday/adapter/net_http_spec.rb +64 -0
- data/spec/faraday/adapter/patron_spec.rb +18 -0
- data/spec/faraday/adapter/rack_spec.rb +8 -0
- data/spec/faraday/adapter/typhoeus_spec.rb +7 -0
- data/spec/faraday/adapter_registry_spec.rb +28 -0
- data/spec/faraday/adapter_spec.rb +55 -0
- data/spec/faraday/composite_read_io_spec.rb +80 -0
- data/spec/faraday/connection_spec.rb +691 -0
- data/spec/faraday/error_spec.rb +0 -57
- data/spec/faraday/middleware_spec.rb +26 -0
- data/spec/faraday/options/env_spec.rb +70 -0
- data/spec/faraday/options/options_spec.rb +297 -0
- data/spec/faraday/options/proxy_options_spec.rb +37 -0
- data/spec/faraday/options/request_options_spec.rb +19 -0
- data/spec/faraday/params_encoders/flat_spec.rb +34 -0
- data/spec/faraday/params_encoders/nested_spec.rb +134 -0
- data/spec/faraday/rack_builder_spec.rb +196 -0
- data/spec/faraday/request/authorization_spec.rb +88 -0
- data/spec/faraday/request/instrumentation_spec.rb +76 -0
- data/spec/faraday/request/multipart_spec.rb +274 -0
- data/spec/faraday/request/retry_spec.rb +242 -0
- data/spec/faraday/request/url_encoded_spec.rb +83 -0
- data/spec/faraday/request_spec.rb +109 -0
- data/spec/faraday/response/logger_spec.rb +220 -0
- data/spec/faraday/response/middleware_spec.rb +68 -0
- data/spec/faraday/response/raise_error_spec.rb +15 -15
- data/spec/faraday/response_spec.rb +75 -0
- data/spec/faraday/utils/headers_spec.rb +82 -0
- data/spec/faraday/utils_spec.rb +56 -0
- data/spec/faraday_spec.rb +37 -0
- data/spec/spec_helper.rb +63 -36
- data/spec/support/disabling_stub.rb +14 -0
- data/spec/support/fake_safe_buffer.rb +15 -0
- data/spec/support/helper_methods.rb +133 -0
- data/spec/support/shared_examples/adapter.rb +104 -0
- data/spec/support/shared_examples/params_encoder.rb +18 -0
- data/spec/support/shared_examples/request_method.rb +234 -0
- data/spec/support/streaming_response_checker.rb +35 -0
- data/spec/support/webmock_rack_app.rb +68 -0
- metadata +66 -38
- data/lib/faraday/deprecate.rb +0 -107
- data/lib/faraday/upload_io.rb +0 -67
- data/spec/faraday/deprecate_spec.rb +0 -69
- data/test/adapters/default_test.rb +0 -14
- data/test/adapters/em_http_test.rb +0 -30
- data/test/adapters/em_synchrony_test.rb +0 -32
- data/test/adapters/excon_test.rb +0 -30
- data/test/adapters/httpclient_test.rb +0 -34
- data/test/adapters/integration.rb +0 -263
- data/test/adapters/logger_test.rb +0 -136
- data/test/adapters/net_http_persistent_test.rb +0 -114
- data/test/adapters/net_http_test.rb +0 -79
- data/test/adapters/patron_test.rb +0 -40
- data/test/adapters/rack_test.rb +0 -38
- data/test/adapters/test_middleware_test.rb +0 -157
- data/test/adapters/typhoeus_test.rb +0 -38
- data/test/authentication_middleware_test.rb +0 -65
- data/test/composite_read_io_test.rb +0 -109
- data/test/connection_test.rb +0 -738
- data/test/env_test.rb +0 -268
- data/test/helper.rb +0 -75
- data/test/live_server.rb +0 -67
- data/test/middleware/instrumentation_test.rb +0 -88
- data/test/middleware/retry_test.rb +0 -282
- data/test/middleware_stack_test.rb +0 -260
- data/test/multibyte.txt +0 -1
- data/test/options_test.rb +0 -333
- data/test/parameters_test.rb +0 -157
- data/test/request_middleware_test.rb +0 -126
- data/test/response_middleware_test.rb +0 -72
- data/test/strawberry.rb +0 -2
- data/test/utils_test.rb +0 -98
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 1d23ec0aefc40d23ccc4410db08092bd29e477309fb8aa6794b3c8401961de10
|
4
|
+
data.tar.gz: c33ca7313dcccbf148266a80aa4e12d4cba96a4feb96ecfc3e8ff50fa06756c5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 8058c22dc6e78bc3d46a9c8a22c458656a1380a4aed62b31e11b9b054fc6791373dd103276fc018148daed3934a724bcb39390bbe88e2762281ff810b61b408d
|
7
|
+
data.tar.gz: 341f3b44148f666bb03f8e7b232fd92e26b8c34d758090e6e82f1276af29ff17d4f62bdb58871254ba48b2232ab58269c71db08df7a4b0c35c53f2c7e9bbe7e8
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,49 @@
|
|
1
1
|
# Faraday Changelog
|
2
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
|
+
|
3
47
|
## v0.17.3
|
4
48
|
|
5
49
|
Fixes:
|
@@ -85,17 +129,17 @@ Fixes:
|
|
85
129
|
|
86
130
|
Features:
|
87
131
|
|
88
|
-
* Allow overriding env proxy
|
89
|
-
* Remove legacy Typhoeus adapter
|
90
|
-
* External Typhoeus Adapter Compatibility
|
91
|
-
* Warn about missing adapter when making a request
|
92
|
-
* Faraday::Adapter::Test stubs now support entire urls (with host)
|
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)
|
93
137
|
|
94
138
|
Fixes:
|
95
139
|
|
96
|
-
* If proxy is manually provided, this takes priority over `find_proxy`
|
97
|
-
* Fixes the behaviour for Excon's open_timeout (not setting write_timeout anymore)
|
98
|
-
* Handle all connection timeout messages in Patron
|
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)
|
99
143
|
|
100
144
|
## v0.13.1
|
101
145
|
|
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -1,367 +1,32 @@
|
|
1
|
-
# Faraday
|
1
|
+
# [][website]
|
2
2
|
|
3
3
|
[](https://rubygems.org/gems/faraday)
|
4
|
-
|
5
|
-
[
|
5
|
+
[](https://codeclimate.com/github/lostisland/faraday/test_coverage)
|
6
|
+
[](https://codeclimate.com/github/lostisland/faraday/maintainability)
|
7
7
|
[](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
8
8
|
|
9
9
|
|
10
|
-
Faraday is an HTTP client
|
10
|
+
Faraday is an HTTP client library that provides a common interface over many
|
11
11
|
adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
|
12
12
|
processing the request/response cycle.
|
13
13
|
|
14
|
-
|
14
|
+
## Getting Started
|
15
15
|
|
16
|
-
|
17
|
-
|
18
|
-
* [Excon][]
|
19
|
-
* [Patron][]
|
20
|
-
* [EventMachine][]
|
21
|
-
* [HTTPClient][]
|
22
|
-
|
23
|
-
Adapters are slowly being moved into their own gems, or bundled with HTTP clients:
|
24
|
-
|
25
|
-
* [Typhoeus][]
|
26
|
-
|
27
|
-
It also includes a Rack adapter for hitting loaded Rack applications through
|
28
|
-
Rack::Test, and a Test adapter for stubbing requests by hand.
|
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
|
-
|
45
|
-
## Usage
|
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
|
-
|
65
|
-
```ruby
|
66
|
-
conn = Faraday.new(:url => 'http://sushi.com') do |faraday|
|
67
|
-
faraday.request :url_encoded # form-encode POST params
|
68
|
-
faraday.response :logger # log requests to $stdout
|
69
|
-
faraday.adapter Faraday.default_adapter # make requests with Net::HTTP
|
70
|
-
end
|
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
|
86
|
-
## GET ##
|
87
|
-
|
88
|
-
response = conn.get '/nigiri/sake.json' # GET http://sushi.com/nigiri/sake.json
|
89
|
-
response.body
|
90
|
-
|
91
|
-
conn.get '/nigiri', { :name => 'Maguro' } # GET http://sushi.com/nigiri?name=Maguro
|
92
|
-
|
93
|
-
conn.get do |req| # GET http://sushi.com/search?page=2&limit=100
|
94
|
-
req.url '/search', :page => 2
|
95
|
-
req.params['limit'] = 100
|
96
|
-
end
|
97
|
-
|
98
|
-
## POST ##
|
99
|
-
|
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:
|
104
|
-
|
105
|
-
```ruby
|
106
|
-
# post payload as JSON instead of "www-form-urlencoded" encoding:
|
107
|
-
conn.post do |req|
|
108
|
-
req.url '/nigiri'
|
109
|
-
req.headers['Content-Type'] = 'application/json'
|
110
|
-
req.body = '{ "name": "Unagi" }'
|
111
|
-
end
|
112
|
-
|
113
|
-
## Per-request options ##
|
114
|
-
|
115
|
-
conn.get do |req|
|
116
|
-
req.url '/search'
|
117
|
-
req.options.timeout = 5 # open/read timeout in seconds
|
118
|
-
req.options.open_timeout = 2 # connection open timeout in seconds
|
119
|
-
end
|
120
|
-
```
|
121
|
-
|
122
|
-
And you can inject arbitrary data into the request using the `context` option:
|
123
|
-
|
124
|
-
```ruby
|
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
|
134
|
-
```
|
135
|
-
|
136
|
-
### Changing how parameters are serialized
|
137
|
-
|
138
|
-
Sometimes you need to send the same URL parameter multiple times with different
|
139
|
-
values. This requires manually setting the parameter encoder and can be done on
|
140
|
-
either per-connection or per-request basis.
|
141
|
-
|
142
|
-
```ruby
|
143
|
-
# per-connection setting
|
144
|
-
conn = Faraday.new :request => { :params_encoder => Faraday::FlatParamsEncoder }
|
145
|
-
|
146
|
-
conn.get do |req|
|
147
|
-
# per-request setting:
|
148
|
-
# req.options.params_encoder = my_encoder
|
149
|
-
req.params['roll'] = ['california', 'philadelphia']
|
150
|
-
end
|
151
|
-
# GET 'http://sushi.com?roll=california&roll=philadelphia'
|
152
|
-
```
|
153
|
-
|
154
|
-
The value of Faraday `params_encoder` can be any object that responds to:
|
155
|
-
|
156
|
-
* `encode(hash) #=> String`
|
157
|
-
* `decode(string) #=> Hash`
|
158
|
-
|
159
|
-
The encoder will affect both how query strings are processed and how POST bodies
|
160
|
-
get serialized. The default encoder is Faraday::NestedParamsEncoder.
|
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
|
-
|
192
|
-
## Advanced middleware usage
|
193
|
-
|
194
|
-
The order in which middleware is stacked is important. Like with Rack, the
|
195
|
-
first middleware on the list wraps all others, while the last middleware is the
|
196
|
-
innermost one, so that must be the adapter.
|
197
|
-
|
198
|
-
```ruby
|
199
|
-
Faraday.new(...) do |conn|
|
200
|
-
# POST/PUT params encoders:
|
201
|
-
conn.request :multipart
|
202
|
-
conn.request :url_encoded
|
203
|
-
|
204
|
-
# add custom middleware
|
205
|
-
conn.use MyMiddleware
|
206
|
-
|
207
|
-
# Last middleware must be the adapter:
|
208
|
-
conn.adapter :net_http
|
209
|
-
end
|
210
|
-
```
|
211
|
-
|
212
|
-
This request middleware setup affects POST/PUT requests in the following way:
|
213
|
-
|
214
|
-
1. `Request::Multipart` checks for files in the payload, otherwise leaves
|
215
|
-
everything untouched;
|
216
|
-
2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
|
217
|
-
already encoded or of another type
|
218
|
-
|
219
|
-
Swapping middleware means giving the other priority. Specifying the
|
220
|
-
"Content-Type" for the request is explicitly stating which middleware should
|
221
|
-
process it.
|
222
|
-
|
223
|
-
Examples:
|
224
|
-
|
225
|
-
```ruby
|
226
|
-
# uploading a file:
|
227
|
-
payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg')
|
228
|
-
|
229
|
-
# "Multipart" middleware detects files and encodes with "multipart/form-data":
|
230
|
-
conn.put '/profile', payload
|
231
|
-
```
|
232
|
-
|
233
|
-
## Writing middleware
|
234
|
-
|
235
|
-
Middleware are classes that implement a `call` instance method. They hook into
|
236
|
-
the request/response cycle.
|
237
|
-
|
238
|
-
```ruby
|
239
|
-
def call(request_env)
|
240
|
-
# do something with the request
|
241
|
-
# request_env[:request_headers].merge!(...)
|
242
|
-
|
243
|
-
@app.call(request_env).on_complete do |response_env|
|
244
|
-
# do something with the response
|
245
|
-
# response_env[:response_headers].merge!(...)
|
246
|
-
end
|
247
|
-
end
|
248
|
-
```
|
249
|
-
|
250
|
-
It's important to do all processing of the response only in the `on_complete`
|
251
|
-
block. This enables middleware to work in parallel mode where requests are
|
252
|
-
asynchronous.
|
253
|
-
|
254
|
-
The `env` is a hash with symbol keys that contains info about the request and,
|
255
|
-
later, response. Some keys are:
|
256
|
-
|
257
|
-
```
|
258
|
-
# request phase
|
259
|
-
:method - :get, :post, ...
|
260
|
-
:url - URI for the current request; also contains GET parameters
|
261
|
-
:body - POST parameters for :post/:put requests
|
262
|
-
:request_headers
|
263
|
-
|
264
|
-
# response phase
|
265
|
-
:status - HTTP response status code, such as 200
|
266
|
-
:body - the response body
|
267
|
-
:response_headers
|
268
|
-
```
|
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
|
-
|
317
|
-
## Using Faraday for testing
|
318
|
-
|
319
|
-
```ruby
|
320
|
-
# It's possible to define stubbed request outside a test adapter block.
|
321
|
-
stubs = Faraday::Adapter::Test::Stubs.new do |stub|
|
322
|
-
stub.get('/tamago') { |env| [200, {}, 'egg'] }
|
323
|
-
end
|
324
|
-
|
325
|
-
# You can pass stubbed request to the test adapter or define them in a block
|
326
|
-
# or a combination of the two.
|
327
|
-
test = Faraday.new do |builder|
|
328
|
-
builder.adapter :test, stubs do |stub|
|
329
|
-
stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]}
|
330
|
-
end
|
331
|
-
end
|
332
|
-
|
333
|
-
# It's also possible to stub additional requests after the connection has
|
334
|
-
# been initialized. This is useful for testing.
|
335
|
-
stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]}
|
336
|
-
|
337
|
-
resp = test.get '/tamago'
|
338
|
-
resp.body # => 'egg'
|
339
|
-
resp = test.get '/ebi'
|
340
|
-
resp.body # => 'shrimp'
|
341
|
-
resp = test.get '/uni'
|
342
|
-
resp.body # => 'urchin'
|
343
|
-
resp = test.get '/else' #=> raises "no such stub" error
|
344
|
-
|
345
|
-
# If you like, you can treat your stubs as mocks by verifying that all of
|
346
|
-
# the stubbed calls were made. NOTE that this feature is still fairly
|
347
|
-
# experimental: It will not verify the order or count of any stub, only that
|
348
|
-
# it was called once during the course of the test.
|
349
|
-
stubs.verify_stubbed_calls
|
350
|
-
```
|
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.
|
351
18
|
|
352
19
|
## Supported Ruby versions
|
353
20
|
|
354
|
-
This library aims to support and is [tested against][
|
21
|
+
This library aims to support and is [tested against][actions] the following Ruby
|
355
22
|
implementations:
|
356
23
|
|
357
|
-
* Ruby
|
358
|
-
* [JRuby][] 1.7+
|
359
|
-
* [Rubinius][] 2+
|
24
|
+
* Ruby 2.4+
|
360
25
|
|
361
26
|
If something doesn't work on one of these Ruby versions, it's a bug.
|
362
27
|
|
363
28
|
This library may inadvertently work (or seem to work) on other Ruby
|
364
|
-
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
|
365
30
|
above.
|
366
31
|
|
367
32
|
If you would like this library to support another Ruby version, you may
|
@@ -375,21 +40,16 @@ of a major release, support for that Ruby version may be dropped.
|
|
375
40
|
|
376
41
|
Do you want to contribute to Faraday?
|
377
42
|
Open the issues page and check for the `help wanted` label!
|
378
|
-
But before you start coding, please read our [Contributing Guide]
|
43
|
+
But before you start coding, please read our [Contributing Guide][contributing]
|
379
44
|
|
380
45
|
## Copyright
|
46
|
+
© 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
|
381
47
|
|
382
|
-
|
383
|
-
|
384
|
-
|
385
|
-
[
|
386
|
-
[
|
387
|
-
[travis]: https://travis-ci.org/lostisland/faraday
|
388
|
-
[excon]: https://github.com/excon/excon#readme
|
389
|
-
[patron]: http://toland.github.io/patron/
|
390
|
-
[eventmachine]: https://github.com/igrigorik/em-http-request#readme
|
391
|
-
[httpclient]: https://github.com/nahi/httpclient
|
392
|
-
[typhoeus]: https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/adapters/faraday.rb
|
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
|
393
53
|
[jruby]: http://jruby.org/
|
394
54
|
[rubinius]: http://rubini.us/
|
395
55
|
[license]: LICENSE.md
|