faraday 0.17.4 → 1.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (135) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +156 -8
  3. data/LICENSE.md +1 -1
  4. data/README.md +16 -358
  5. data/Rakefile +1 -7
  6. data/examples/client_spec.rb +97 -0
  7. data/examples/client_test.rb +118 -0
  8. data/lib/faraday/adapter/test.rb +118 -69
  9. data/lib/faraday/adapter/typhoeus.rb +4 -1
  10. data/lib/faraday/adapter.rb +72 -22
  11. data/lib/faraday/adapter_registry.rb +30 -0
  12. data/lib/faraday/autoload.rb +39 -36
  13. data/lib/faraday/connection.rb +343 -185
  14. data/lib/faraday/dependency_loader.rb +37 -0
  15. data/lib/faraday/encoders/flat_params_encoder.rb +105 -0
  16. data/lib/faraday/encoders/nested_params_encoder.rb +176 -0
  17. data/lib/faraday/error.rb +29 -35
  18. data/lib/faraday/file_part.rb +128 -0
  19. data/lib/faraday/logging/formatter.rb +105 -0
  20. data/lib/faraday/methods.rb +6 -0
  21. data/lib/faraday/middleware.rb +19 -25
  22. data/lib/faraday/middleware_registry.rb +129 -0
  23. data/lib/faraday/options/connection_options.rb +22 -0
  24. data/lib/faraday/options/env.rb +181 -0
  25. data/lib/faraday/options/proxy_options.rb +32 -0
  26. data/lib/faraday/options/request_options.rb +22 -0
  27. data/lib/faraday/options/ssl_options.rb +59 -0
  28. data/lib/faraday/options.rb +36 -191
  29. data/lib/faraday/param_part.rb +53 -0
  30. data/lib/faraday/parameters.rb +4 -197
  31. data/lib/faraday/rack_builder.rb +76 -64
  32. data/lib/faraday/request/authorization.rb +51 -30
  33. data/lib/faraday/request/basic_authentication.rb +14 -7
  34. data/lib/faraday/request/instrumentation.rb +45 -27
  35. data/lib/faraday/request/multipart.rb +86 -48
  36. data/lib/faraday/request/retry.rb +197 -171
  37. data/lib/faraday/request/token_authentication.rb +15 -10
  38. data/lib/faraday/request/url_encoded.rb +43 -23
  39. data/lib/faraday/request.rb +86 -44
  40. data/lib/faraday/response/logger.rb +22 -69
  41. data/lib/faraday/response/raise_error.rb +49 -18
  42. data/lib/faraday/response.rb +24 -20
  43. data/lib/faraday/utils/headers.rb +139 -0
  44. data/lib/faraday/utils/params_hash.rb +61 -0
  45. data/lib/faraday/utils.rb +38 -247
  46. data/lib/faraday/version.rb +5 -0
  47. data/lib/faraday.rb +127 -189
  48. data/spec/external_adapters/faraday_specs_setup.rb +14 -0
  49. data/spec/faraday/adapter/em_http_spec.rb +49 -0
  50. data/spec/faraday/adapter/em_synchrony_spec.rb +18 -0
  51. data/spec/faraday/adapter/excon_spec.rb +49 -0
  52. data/spec/faraday/adapter/httpclient_spec.rb +73 -0
  53. data/spec/faraday/adapter/net_http_spec.rb +64 -0
  54. data/spec/faraday/adapter/patron_spec.rb +18 -0
  55. data/spec/faraday/adapter/rack_spec.rb +8 -0
  56. data/spec/faraday/adapter/test_spec.rb +377 -0
  57. data/spec/faraday/adapter/typhoeus_spec.rb +7 -0
  58. data/spec/faraday/adapter_registry_spec.rb +28 -0
  59. data/spec/faraday/adapter_spec.rb +55 -0
  60. data/spec/faraday/composite_read_io_spec.rb +80 -0
  61. data/spec/faraday/connection_spec.rb +736 -0
  62. data/spec/faraday/error_spec.rb +12 -54
  63. data/spec/faraday/middleware_spec.rb +52 -0
  64. data/spec/faraday/options/env_spec.rb +70 -0
  65. data/spec/faraday/options/options_spec.rb +297 -0
  66. data/spec/faraday/options/proxy_options_spec.rb +44 -0
  67. data/spec/faraday/options/request_options_spec.rb +19 -0
  68. data/spec/faraday/params_encoders/flat_spec.rb +42 -0
  69. data/spec/faraday/params_encoders/nested_spec.rb +142 -0
  70. data/spec/faraday/rack_builder_spec.rb +345 -0
  71. data/spec/faraday/request/authorization_spec.rb +96 -0
  72. data/spec/faraday/request/instrumentation_spec.rb +76 -0
  73. data/spec/faraday/request/multipart_spec.rb +302 -0
  74. data/spec/faraday/request/retry_spec.rb +242 -0
  75. data/spec/faraday/request/url_encoded_spec.rb +83 -0
  76. data/spec/faraday/request_spec.rb +120 -0
  77. data/spec/faraday/response/logger_spec.rb +220 -0
  78. data/spec/faraday/response/middleware_spec.rb +68 -0
  79. data/spec/faraday/response/raise_error_spec.rb +78 -15
  80. data/spec/faraday/response_spec.rb +75 -0
  81. data/spec/faraday/utils/headers_spec.rb +82 -0
  82. data/spec/faraday/utils_spec.rb +56 -0
  83. data/spec/faraday_spec.rb +37 -0
  84. data/spec/spec_helper.rb +63 -36
  85. data/spec/support/disabling_stub.rb +14 -0
  86. data/spec/support/fake_safe_buffer.rb +15 -0
  87. data/spec/support/helper_methods.rb +133 -0
  88. data/spec/support/shared_examples/adapter.rb +105 -0
  89. data/spec/support/shared_examples/params_encoder.rb +18 -0
  90. data/spec/support/shared_examples/request_method.rb +262 -0
  91. data/spec/support/streaming_response_checker.rb +35 -0
  92. data/spec/support/webmock_rack_app.rb +68 -0
  93. metadata +194 -48
  94. data/lib/faraday/adapter/em_http.rb +0 -243
  95. data/lib/faraday/adapter/em_http_ssl_patch.rb +0 -56
  96. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +0 -66
  97. data/lib/faraday/adapter/em_synchrony.rb +0 -106
  98. data/lib/faraday/adapter/excon.rb +0 -82
  99. data/lib/faraday/adapter/httpclient.rb +0 -128
  100. data/lib/faraday/adapter/net_http.rb +0 -153
  101. data/lib/faraday/adapter/net_http_persistent.rb +0 -68
  102. data/lib/faraday/adapter/patron.rb +0 -95
  103. data/lib/faraday/adapter/rack.rb +0 -58
  104. data/lib/faraday/deprecate.rb +0 -109
  105. data/lib/faraday/upload_io.rb +0 -67
  106. data/spec/faraday/deprecate_spec.rb +0 -147
  107. data/test/adapters/default_test.rb +0 -14
  108. data/test/adapters/em_http_test.rb +0 -30
  109. data/test/adapters/em_synchrony_test.rb +0 -32
  110. data/test/adapters/excon_test.rb +0 -30
  111. data/test/adapters/httpclient_test.rb +0 -34
  112. data/test/adapters/integration.rb +0 -263
  113. data/test/adapters/logger_test.rb +0 -136
  114. data/test/adapters/net_http_persistent_test.rb +0 -114
  115. data/test/adapters/net_http_test.rb +0 -79
  116. data/test/adapters/patron_test.rb +0 -40
  117. data/test/adapters/rack_test.rb +0 -38
  118. data/test/adapters/test_middleware_test.rb +0 -157
  119. data/test/adapters/typhoeus_test.rb +0 -38
  120. data/test/authentication_middleware_test.rb +0 -65
  121. data/test/composite_read_io_test.rb +0 -109
  122. data/test/connection_test.rb +0 -738
  123. data/test/env_test.rb +0 -268
  124. data/test/helper.rb +0 -75
  125. data/test/live_server.rb +0 -67
  126. data/test/middleware/instrumentation_test.rb +0 -88
  127. data/test/middleware/retry_test.rb +0 -282
  128. data/test/middleware_stack_test.rb +0 -260
  129. data/test/multibyte.txt +0 -1
  130. data/test/options_test.rb +0 -333
  131. data/test/parameters_test.rb +0 -157
  132. data/test/request_middleware_test.rb +0 -126
  133. data/test/response_middleware_test.rb +0 -72
  134. data/test/strawberry.rb +0 -2
  135. data/test/utils_test.rb +0 -98
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b53b5c1f4239a1b798cc39d21c2ba204f1f1682c68650dfd5abd2a15acad8f4c
4
- data.tar.gz: 494d3b48b2b5cbd07433d786e3dcac4570c5a8319b6bdbbba481957ec18ad667
3
+ metadata.gz: f6441da03048f7371bd0cb898dd3e27c7be6382c67fc4901883e9dbe9841b56f
4
+ data.tar.gz: 0beb3f2da75282655fc46cd5540de96d5fef259dd35193ec9eb0d3163cc959d2
5
5
  SHA512:
6
- metadata.gz: e473d6f5f690de91f62283db0364e3a304077dd3445b924a9636a7691593d8d7abf715d5e1ccd7838364a85d4e8611bc4c7d6ab1195b5f0c30d24e32a9d6946c
7
- data.tar.gz: 84f629bd1dce5dc09637fec05c46d8f78d018b7f89adc4b7a945e50f3edc0cc2077733ca74b41b92e5afb02876f25168b6e40832cf40bebe5c9b63d53fe6a9ac
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 (#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)
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` (#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)
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
@@ -1,4 +1,4 @@
1
- Copyright (c) 2009-2017 Rick Olson, Zack Hobson
1
+ Copyright (c) 2009-2020 Rick Olson, Zack Hobson
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
data/README.md CHANGED
@@ -1,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
- [![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)
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 lib that provides a common interface over many
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
- Faraday supports these adapters out of the box:
12
+ ## Getting Started
15
13
 
16
- * [Net::HTTP][net_http] _(default)_
17
- * [Net::HTTP::Persistent][persistent]
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][travis] the following Ruby
19
+ This library aims to support and is [tested against][actions] the following Ruby
355
20
  implementations:
356
21
 
357
- * Ruby 1.9.3+
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](https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md)
41
+ But before you start coding, please read our [Contributing Guide][contributing]
379
42
 
380
43
  ## Copyright
44
+ &copy; 2009 - 2020, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
381
45
 
382
- Copyright (c) 2009-2017 [Rick Olson](mailto:technoweenie@gmail.com), Zack Hobson.
383
- See [LICENSE][] for details.
384
-
385
- [net_http]: http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html
386
- [persistent]: https://github.com/drbrain/net-http-persistent
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 :default => :test
9
-
10
- desc "Run all tests"
11
- task :test => :spec do
12
- exec 'script/test'
13
- end
7
+ task default: :spec