faraday 0.17.4 → 1.8.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +156 -8
- data/LICENSE.md +1 -1
- data/README.md +16 -358
- data/Rakefile +1 -7
- data/examples/client_spec.rb +97 -0
- data/examples/client_test.rb +118 -0
- data/lib/faraday/adapter/test.rb +118 -69
- data/lib/faraday/adapter/typhoeus.rb +4 -1
- data/lib/faraday/adapter.rb +72 -22
- data/lib/faraday/adapter_registry.rb +30 -0
- data/lib/faraday/autoload.rb +39 -36
- data/lib/faraday/connection.rb +343 -185
- data/lib/faraday/dependency_loader.rb +37 -0
- data/lib/faraday/encoders/flat_params_encoder.rb +105 -0
- data/lib/faraday/encoders/nested_params_encoder.rb +176 -0
- data/lib/faraday/error.rb +29 -35
- data/lib/faraday/file_part.rb +128 -0
- data/lib/faraday/logging/formatter.rb +105 -0
- data/lib/faraday/methods.rb +6 -0
- data/lib/faraday/middleware.rb +19 -25
- data/lib/faraday/middleware_registry.rb +129 -0
- data/lib/faraday/options/connection_options.rb +22 -0
- data/lib/faraday/options/env.rb +181 -0
- data/lib/faraday/options/proxy_options.rb +32 -0
- data/lib/faraday/options/request_options.rb +22 -0
- data/lib/faraday/options/ssl_options.rb +59 -0
- data/lib/faraday/options.rb +36 -191
- data/lib/faraday/param_part.rb +53 -0
- data/lib/faraday/parameters.rb +4 -197
- data/lib/faraday/rack_builder.rb +76 -64
- data/lib/faraday/request/authorization.rb +51 -30
- data/lib/faraday/request/basic_authentication.rb +14 -7
- data/lib/faraday/request/instrumentation.rb +45 -27
- data/lib/faraday/request/multipart.rb +86 -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/request.rb +86 -44
- data/lib/faraday/response/logger.rb +22 -69
- data/lib/faraday/response/raise_error.rb +49 -18
- data/lib/faraday/response.rb +24 -20
- data/lib/faraday/utils/headers.rb +139 -0
- data/lib/faraday/utils/params_hash.rb +61 -0
- data/lib/faraday/utils.rb +38 -247
- data/lib/faraday/version.rb +5 -0
- data/lib/faraday.rb +127 -189
- data/spec/external_adapters/faraday_specs_setup.rb +14 -0
- data/spec/faraday/adapter/em_http_spec.rb +49 -0
- data/spec/faraday/adapter/em_synchrony_spec.rb +18 -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_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/test_spec.rb +377 -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 +736 -0
- data/spec/faraday/error_spec.rb +12 -54
- data/spec/faraday/middleware_spec.rb +52 -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 +44 -0
- data/spec/faraday/options/request_options_spec.rb +19 -0
- data/spec/faraday/params_encoders/flat_spec.rb +42 -0
- data/spec/faraday/params_encoders/nested_spec.rb +142 -0
- data/spec/faraday/rack_builder_spec.rb +345 -0
- data/spec/faraday/request/authorization_spec.rb +96 -0
- data/spec/faraday/request/instrumentation_spec.rb +76 -0
- data/spec/faraday/request/multipart_spec.rb +302 -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 +120 -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 +78 -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 +105 -0
- data/spec/support/shared_examples/params_encoder.rb +18 -0
- data/spec/support/shared_examples/request_method.rb +262 -0
- data/spec/support/streaming_response_checker.rb +35 -0
- data/spec/support/webmock_rack_app.rb +68 -0
- metadata +194 -48
- data/lib/faraday/adapter/em_http.rb +0 -243
- data/lib/faraday/adapter/em_http_ssl_patch.rb +0 -56
- data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +0 -66
- data/lib/faraday/adapter/em_synchrony.rb +0 -106
- data/lib/faraday/adapter/excon.rb +0 -82
- data/lib/faraday/adapter/httpclient.rb +0 -128
- data/lib/faraday/adapter/net_http.rb +0 -153
- data/lib/faraday/adapter/net_http_persistent.rb +0 -68
- data/lib/faraday/adapter/patron.rb +0 -95
- data/lib/faraday/adapter/rack.rb +0 -58
- data/lib/faraday/deprecate.rb +0 -109
- data/lib/faraday/upload_io.rb +0 -67
- data/spec/faraday/deprecate_spec.rb +0 -147
- 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: f6441da03048f7371bd0cb898dd3e27c7be6382c67fc4901883e9dbe9841b56f
|
4
|
+
data.tar.gz: 0beb3f2da75282655fc46cd5540de96d5fef259dd35193ec9eb0d3163cc959d2
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 1ab1aa0e0c68c9348d9e180a903f01f2517bd38672fe1bdf056ceab4729e841944173e47dc26aa1b4fe16b2779f1a8102914ed594ea92d08feff6dc944412f0b
|
7
|
+
data.tar.gz: bc43fbac427062861e79d5328b60886a5b9c8783f707faa1fcfad064b9c6945f6a4e2a97dbad9ecadc1c1620b5327d651a764962764b7fc86e6d2fbd84ad0b4b
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,153 @@
|
|
1
1
|
# Faraday Changelog
|
2
2
|
|
3
|
+
## [v1.3.0](https://github.com/lostisland/faraday/releases/tag/v1.3.0) (2020-12-31)
|
4
|
+
|
5
|
+
### Highlights
|
6
|
+
Faraday v1.3.0 is the first release to officially support Ruby 3.0 in the CI pipeline 🎉 🍾!
|
7
|
+
|
8
|
+
This is also the first release with a previously "included" adapter (Net::HTTP) being isolated into a [separate gem](https://github.com/lostisland/faraday-net_http) 🎊!
|
9
|
+
The new adapter is added to Faraday as a dependency for now, so that means full backwards-compatibility, but just to be safe be careful when upgrading!
|
10
|
+
|
11
|
+
This is a huge step towards are Faraday v2.0 objective of pushing adapters and middleware into separate gems.
|
12
|
+
Many thanks to the Faraday Team, @JanDintel and everyone who attended the [ROSS Conf remote event](https://www.rossconf.io/event/remote/)
|
13
|
+
|
14
|
+
### Features
|
15
|
+
|
16
|
+
* Improves consistency with Faraday::Error and Faraday::RaiseError (#1229, @qsona, @iMacTia)
|
17
|
+
|
18
|
+
### Fixes
|
19
|
+
|
20
|
+
* Don't assign to global ::Timer (#1227, @bpo)
|
21
|
+
|
22
|
+
### Documentation
|
23
|
+
|
24
|
+
* CHANGELOG: add releases after 1.0 (#1225, @olleolleolle)
|
25
|
+
* Improves retry middleware documentation. (#1228, @iMacTia)
|
26
|
+
|
27
|
+
### Misc
|
28
|
+
|
29
|
+
* Move out Net::HTTP adapter (#1222, @JanDintel, @iMacTia)
|
30
|
+
* Adds Ruby 3.0 to CI Matrix (#1226, @iMacTia)
|
31
|
+
|
32
|
+
|
33
|
+
## [v1.2.0](https://github.com/lostisland/faraday/releases/tag/v1.2.0) (2020-12-23)
|
34
|
+
|
35
|
+
### Features
|
36
|
+
|
37
|
+
* Introduces `on_request` and `on_complete` methods in `Faraday::Middleware`. (#1194, @iMacTia)
|
38
|
+
|
39
|
+
### Fixes
|
40
|
+
|
41
|
+
* Require 'date' to avoid retry exception (#1206, @rustygeldmacher)
|
42
|
+
* Fix rdebug recursion issue (#1205, @native-api)
|
43
|
+
* Update call to `em_http_ssl_patch` (#1202, @kylekeesling)
|
44
|
+
* `EmHttp` adapter: drop superfluous loaded? check (#1213, @olleolleolle)
|
45
|
+
* Avoid 1 use of keyword hackery (#1211, @grosser)
|
46
|
+
* Fix #1219 `Net::HTTP` still uses env proxy (#1221, @iMacTia)
|
47
|
+
|
48
|
+
### Documentation
|
49
|
+
|
50
|
+
* Add comment in gemspec to explain exposure of `examples` and `spec` folders. (#1192, @iMacTia)
|
51
|
+
* Adapters, how to create them (#1193, @olleolleolle)
|
52
|
+
* Update documentation on using the logger (#1196, @tijmenb)
|
53
|
+
* Adjust the retry documentation and spec to align with implementation (#1198, @nbeyer)
|
54
|
+
|
55
|
+
### Misc
|
56
|
+
|
57
|
+
* Test against ruby head (#1208, @grosser)
|
58
|
+
|
59
|
+
## [v1.1.0](https://github.com/lostisland/faraday/releases/tag/v1.1.0) (2020-10-17)
|
60
|
+
|
61
|
+
### Features
|
62
|
+
|
63
|
+
* Makes parameters sorting configurable (#1162 @wishdev)
|
64
|
+
* Introduces `flat_encode` option for multipart adapter. (#1163 @iMacTia)
|
65
|
+
* Include request info in exceptions raised by RaiseError Middleware (#1181 @SandroDamilano)
|
66
|
+
|
67
|
+
### Fixes
|
68
|
+
|
69
|
+
* Avoid `last arg as keyword param` warning when building user middleware on Ruby 2.7 (#1153 @dgholz)
|
70
|
+
* Limits net-http-persistent version to < 4.0 (#1156 @iMacTia)
|
71
|
+
* Update `typhoeus` to new stable version (`1.4`) (#1159 @AlexWayfer)
|
72
|
+
* Properly fix test failure with Rack 2.1+. (#1171 @voxik)
|
73
|
+
|
74
|
+
### Documentation
|
75
|
+
|
76
|
+
* Improves documentation on how to contribute to the site by using Docker. (#1175 @iMacTia)
|
77
|
+
* Remove retry_change_requests from documentation (#1185 @stim371)
|
78
|
+
|
79
|
+
### Misc
|
80
|
+
|
81
|
+
* Link from GitHub Actions badge to CI workflow (#1141 @olleolleolle)
|
82
|
+
* Return tests of `Test` adapter (#1147 @AlexWayfer)
|
83
|
+
* Add 1.0 release to wording in CONTRIBUTING (#1155 @olleolleolle)
|
84
|
+
* Fix linting bumping Rubocop to 0.90.0 (#1182 @iMacTia)
|
85
|
+
* Drop `git ls-files` in gemspec (#1183 @utkarsh2102)
|
86
|
+
* Upgrade CI to ruby/setup-ruby (#1187 @gogainda)
|
87
|
+
|
88
|
+
## [v1.0.1](https://github.com/lostisland/faraday/releases/tag/v1.0.1) (2020-03-29)
|
89
|
+
|
90
|
+
### Fixes
|
91
|
+
|
92
|
+
* Use Net::HTTP#start(&block) to ensure closed TCP connections (#1117)
|
93
|
+
* Fully qualify constants to be checked (#1122)
|
94
|
+
* Allows `parse` method to be private/protected in response middleware (#1123)
|
95
|
+
* Encode Spaces in Query Strings as '%20' Instead of '+' (#1125)
|
96
|
+
* Limits rack to v2.0.x (#1127)
|
97
|
+
* Adapter Registry reads also use mutex (#1136)
|
98
|
+
|
99
|
+
### Documentation
|
100
|
+
|
101
|
+
* Retry middleware documentation fix (#1109)
|
102
|
+
* Docs(retry): precise usage of retry-after (#1111)
|
103
|
+
* README: Link the logo to the website (#1112)
|
104
|
+
* Website: add search bar (#1116)
|
105
|
+
* Fix request/response mix-up in docs text (#1132)
|
106
|
+
|
107
|
+
## v1.0
|
108
|
+
|
109
|
+
Features:
|
110
|
+
|
111
|
+
* Add #trace support to Faraday::Connection #861 (@technoweenie)
|
112
|
+
* Add the log formatter that is easy to override and safe to inherit #889 (@prikha)
|
113
|
+
* Support standalone adapters #941 (@iMacTia)
|
114
|
+
* Introduce Faraday::ConflictError for 409 response code #979 (@lucasmoreno)
|
115
|
+
* Add support for setting `read_timeout` option separately #1003 (@springerigor)
|
116
|
+
* Refactor and cleanup timeout settings across adapters #1022 (@technoweenie)
|
117
|
+
* Create ParamPart class to allow multipart posts with JSON content and file upload at the same time #1017 (@jeremy-israel)
|
118
|
+
* Copy UploadIO const -> FilePart for consistency with ParamPart #1018, #1021 (@technoweenie)
|
119
|
+
* Implement streaming responses in the Excon adapter #1026 (@technoweenie)
|
120
|
+
* Add default implementation of `Middleware#close`. #1069 (@ioquatix)
|
121
|
+
* Add `Adapter#close` so that derived classes can call super. #1091 (@ioquatix)
|
122
|
+
* Add log_level option to logger default formatter #1079 (@amrrbakry)
|
123
|
+
* Fix empty array for FlatParamsEncoder `{key: []} -> "key="` #1084 (@mrexox)
|
124
|
+
|
125
|
+
Bugs:
|
126
|
+
|
127
|
+
* Explicitly require date for DateTime library in Retry middleware #844 (@nickpresta)
|
128
|
+
* Refactor Adapter as final endpoints #846 (@iMacTia)
|
129
|
+
* Separate Request and Response bodies in Faraday::Env #847 (@iMacTia)
|
130
|
+
* Implement Faraday::Connection#options to make HTTP requests with the OPTIONS verb. #857 (@technoweenie)
|
131
|
+
* Multipart: Drop Ruby 1.8 String behavior compat #892 (@olleolleolle)
|
132
|
+
* Fix Ruby warnings in Faraday::Options.memoized #962 (@technoweenie)
|
133
|
+
* Allow setting min/max SSL version for a Net::HTTP::Persistent connection #972, #973 (@bdewater, @olleolleolle)
|
134
|
+
* Fix instances of frozen empty string literals #1040 (@BobbyMcWho)
|
135
|
+
* remove temp_proxy and improve proxy tests #1063 (@technoweenie)
|
136
|
+
* improve error initializer consistency #1095 (@technoweenie)
|
137
|
+
|
138
|
+
Misc:
|
139
|
+
|
140
|
+
* Convert minitest suite to RSpec #832 (@iMacTia, with help from @gaynetdinov, @Insti, @technoweenie)
|
141
|
+
* Major effort to update code to RuboCop standards. #854 (@olleolleolle, @iMacTia, @technoweenie, @htwroclau, @jherdman, @Drenmi, @Insti)
|
142
|
+
* Rubocop #1044, #1047 (@BobbyMcWho, @olleolleolle)
|
143
|
+
* Documentation tweaks (@adsteel, @Hubro, @iMacTia, @olleolleolle, @technoweenie)
|
144
|
+
* Update license year #981 (@Kevin-Kawai)
|
145
|
+
* Configure Jekyll plugin jekyll-remote-theme to support Docker usage #999 (@Lewiscowles1986)
|
146
|
+
* Fix Ruby 2.7 warnings #1009 (@tenderlove)
|
147
|
+
* Cleanup adapter connections #1023 (@technoweenie)
|
148
|
+
* Describe clearing cached stubs #1045 (@viraptor)
|
149
|
+
* Add project metadata to the gemspec #1046 (@orien)
|
150
|
+
|
3
151
|
## v0.17.3
|
4
152
|
|
5
153
|
Fixes:
|
@@ -85,17 +233,17 @@ Fixes:
|
|
85
233
|
|
86
234
|
Features:
|
87
235
|
|
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)
|
236
|
+
* Allow overriding env proxy #754 (@iMacTia)
|
237
|
+
* Remove legacy Typhoeus adapter #715 (@olleolleolle)
|
238
|
+
* External Typhoeus Adapter Compatibility #748 (@iMacTia)
|
239
|
+
* Warn about missing adapter when making a request #743 (@antstorm)
|
240
|
+
* Faraday::Adapter::Test stubs now support entire urls (with host) #741 (@erik-escobedo)
|
93
241
|
|
94
242
|
Fixes:
|
95
243
|
|
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
|
244
|
+
* If proxy is manually provided, this takes priority over `find_proxy` #724 (@iMacTia)
|
245
|
+
* Fixes the behaviour for Excon's open_timeout (not setting write_timeout anymore) #731 (@apachelogger)
|
246
|
+
* Handle all connection timeout messages in Patron #687 (@stayhero)
|
99
247
|
|
100
248
|
## v0.13.1
|
101
249
|
|
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -1,367 +1,30 @@
|
|
1
|
-
# Faraday
|
1
|
+
# [![Faraday](./docs/assets/img/repo-card-slim.png)][website]
|
2
2
|
|
3
3
|
[![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
|
4
|
-
[![
|
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)
|
4
|
+
[![GitHub Actions CI](https://github.com/lostisland/faraday/workflows/CI/badge.svg)](https://github.com/lostisland/faraday/actions?query=workflow%3ACI)
|
7
5
|
[![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
8
6
|
|
9
7
|
|
10
|
-
Faraday is an HTTP client
|
8
|
+
Faraday is an HTTP client library that provides a common interface over many
|
11
9
|
adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
|
12
10
|
processing the request/response cycle.
|
13
11
|
|
14
|
-
|
12
|
+
## Getting Started
|
15
13
|
|
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
|
-
```
|
14
|
+
The best starting point is the [Faraday Website][website], with its introduction and explanation.
|
15
|
+
Need more details? See the [Faraday API Documentation][apidoc] to see how it works internally.
|
351
16
|
|
352
17
|
## Supported Ruby versions
|
353
18
|
|
354
|
-
This library aims to support and is [tested against][
|
19
|
+
This library aims to support and is [tested against][actions] the following Ruby
|
355
20
|
implementations:
|
356
21
|
|
357
|
-
* Ruby
|
358
|
-
* [JRuby][] 1.7+
|
359
|
-
* [Rubinius][] 2+
|
22
|
+
* Ruby 2.4+
|
360
23
|
|
361
24
|
If something doesn't work on one of these Ruby versions, it's a bug.
|
362
25
|
|
363
26
|
This library may inadvertently work (or seem to work) on other Ruby
|
364
|
-
implementations, however support will only be provided for the versions listed
|
27
|
+
implementations and versions, however support will only be provided for the versions listed
|
365
28
|
above.
|
366
29
|
|
367
30
|
If you would like this library to support another Ruby version, you may
|
@@ -375,21 +38,16 @@ of a major release, support for that Ruby version may be dropped.
|
|
375
38
|
|
376
39
|
Do you want to contribute to Faraday?
|
377
40
|
Open the issues page and check for the `help wanted` label!
|
378
|
-
But before you start coding, please read our [Contributing Guide]
|
41
|
+
But before you start coding, please read our [Contributing Guide][contributing]
|
379
42
|
|
380
43
|
## Copyright
|
44
|
+
© 2009 - 2020, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
|
381
45
|
|
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
|
46
|
+
[website]: https://lostisland.github.io/faraday
|
47
|
+
[faraday_team]: https://lostisland.github.io/faraday/team
|
48
|
+
[contributing]: https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md
|
49
|
+
[apidoc]: https://www.rubydoc.info/github/lostisland/faraday
|
50
|
+
[actions]: https://github.com/lostisland/faraday/actions
|
393
51
|
[jruby]: http://jruby.org/
|
394
52
|
[rubinius]: http://rubini.us/
|
395
53
|
[license]: LICENSE.md
|
data/Rakefile
CHANGED
@@ -1,13 +1,7 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
|
-
require 'rake/testtask'
|
4
3
|
require 'rspec/core/rake_task'
|
5
4
|
|
6
5
|
RSpec::Core::RakeTask.new(:spec)
|
7
6
|
|
8
|
-
task :
|
9
|
-
|
10
|
-
desc "Run all tests"
|
11
|
-
task :test => :spec do
|
12
|
-
exec 'script/test'
|
13
|
-
end
|
7
|
+
task default: :spec
|