faraday 0.16.0 → 0.17.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (90) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +232 -0
  3. data/LICENSE.md +1 -1
  4. data/README.md +358 -18
  5. data/Rakefile +13 -0
  6. data/lib/faraday/adapter/em_http.rb +97 -140
  7. data/lib/faraday/adapter/em_http_ssl_patch.rb +17 -23
  8. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +15 -18
  9. data/lib/faraday/adapter/em_synchrony.rb +60 -104
  10. data/lib/faraday/adapter/excon.rb +55 -100
  11. data/lib/faraday/adapter/httpclient.rb +39 -61
  12. data/lib/faraday/adapter/net_http.rb +51 -103
  13. data/lib/faraday/adapter/net_http_persistent.rb +28 -49
  14. data/lib/faraday/adapter/patron.rb +35 -54
  15. data/lib/faraday/adapter/rack.rb +12 -28
  16. data/lib/faraday/adapter/test.rb +53 -86
  17. data/lib/faraday/adapter/typhoeus.rb +1 -4
  18. data/lib/faraday/adapter.rb +22 -36
  19. data/lib/faraday/autoload.rb +36 -47
  20. data/lib/faraday/connection.rb +179 -321
  21. data/lib/faraday/deprecate.rb +109 -0
  22. data/lib/faraday/error.rb +79 -21
  23. data/lib/faraday/middleware.rb +28 -4
  24. data/lib/faraday/options.rb +183 -32
  25. data/lib/faraday/parameters.rb +197 -4
  26. data/lib/faraday/rack_builder.rb +55 -66
  27. data/lib/faraday/request/authorization.rb +30 -42
  28. data/lib/faraday/request/basic_authentication.rb +7 -14
  29. data/lib/faraday/request/instrumentation.rb +27 -45
  30. data/lib/faraday/request/multipart.rb +48 -79
  31. data/lib/faraday/request/retry.rb +171 -197
  32. data/lib/faraday/request/token_authentication.rb +10 -15
  33. data/lib/faraday/request/url_encoded.rb +23 -41
  34. data/lib/faraday/request.rb +36 -68
  35. data/lib/faraday/response/logger.rb +69 -22
  36. data/lib/faraday/response/raise_error.rb +18 -36
  37. data/lib/faraday/response.rb +13 -20
  38. data/lib/faraday/upload_io.rb +67 -0
  39. data/lib/faraday/utils.rb +245 -28
  40. data/lib/faraday.rb +174 -93
  41. data/spec/faraday/deprecate_spec.rb +147 -0
  42. data/spec/faraday/error_spec.rb +102 -0
  43. data/spec/faraday/response/raise_error_spec.rb +106 -0
  44. data/spec/spec_helper.rb +105 -0
  45. data/test/adapters/default_test.rb +14 -0
  46. data/test/adapters/em_http_test.rb +30 -0
  47. data/test/adapters/em_synchrony_test.rb +32 -0
  48. data/test/adapters/excon_test.rb +30 -0
  49. data/test/adapters/httpclient_test.rb +34 -0
  50. data/test/adapters/integration.rb +263 -0
  51. data/test/adapters/logger_test.rb +136 -0
  52. data/test/adapters/net_http_persistent_test.rb +114 -0
  53. data/test/adapters/net_http_test.rb +79 -0
  54. data/test/adapters/patron_test.rb +40 -0
  55. data/test/adapters/rack_test.rb +38 -0
  56. data/test/adapters/test_middleware_test.rb +157 -0
  57. data/test/adapters/typhoeus_test.rb +38 -0
  58. data/test/authentication_middleware_test.rb +65 -0
  59. data/test/composite_read_io_test.rb +109 -0
  60. data/test/connection_test.rb +738 -0
  61. data/test/env_test.rb +268 -0
  62. data/test/helper.rb +75 -0
  63. data/test/live_server.rb +67 -0
  64. data/test/middleware/instrumentation_test.rb +88 -0
  65. data/test/middleware/retry_test.rb +282 -0
  66. data/test/middleware_stack_test.rb +260 -0
  67. data/test/multibyte.txt +1 -0
  68. data/test/options_test.rb +333 -0
  69. data/test/parameters_test.rb +157 -0
  70. data/test/request_middleware_test.rb +126 -0
  71. data/test/response_middleware_test.rb +72 -0
  72. data/test/strawberry.rb +2 -0
  73. data/test/utils_test.rb +98 -0
  74. metadata +50 -25
  75. data/lib/faraday/adapter_registry.rb +0 -28
  76. data/lib/faraday/dependency_loader.rb +0 -37
  77. data/lib/faraday/encoders/flat_params_encoder.rb +0 -94
  78. data/lib/faraday/encoders/nested_params_encoder.rb +0 -171
  79. data/lib/faraday/file_part.rb +0 -128
  80. data/lib/faraday/logging/formatter.rb +0 -92
  81. data/lib/faraday/middleware_registry.rb +0 -129
  82. data/lib/faraday/options/connection_options.rb +0 -22
  83. data/lib/faraday/options/env.rb +0 -181
  84. data/lib/faraday/options/proxy_options.rb +0 -28
  85. data/lib/faraday/options/request_options.rb +0 -21
  86. data/lib/faraday/options/ssl_options.rb +0 -59
  87. data/lib/faraday/param_part.rb +0 -53
  88. data/lib/faraday/utils/headers.rb +0 -139
  89. data/lib/faraday/utils/params_hash.rb +0 -61
  90. data/spec/external_adapters/faraday_specs_setup.rb +0 -14
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 010e4dd27187eb834e8a0c185cab419a1b69c6e3f8a5728f6681109b7848091d
4
- data.tar.gz: ccd678f8acf84929c15a19b7a6ca1b22b2d634eabfae21c84c4a0f0ba97fb8b6
3
+ metadata.gz: b53b5c1f4239a1b798cc39d21c2ba204f1f1682c68650dfd5abd2a15acad8f4c
4
+ data.tar.gz: 494d3b48b2b5cbd07433d786e3dcac4570c5a8319b6bdbbba481957ec18ad667
5
5
  SHA512:
6
- metadata.gz: 150271b18c60bf5b55cc7e74f39fb01d6c83eecc39119d425fe8d399829ba728183900a5a948dbb874f432fc95996b88c367e87b5274b45addbd15d6175d7bc0
7
- data.tar.gz: 3f4ef0b5d787aeffef29d79af04297a62a6b1ae77f034858b7d68ac4bdcfc00734c976cb8dff8b76b0af007590c6f4a5376797c14d3798cc13193aed96689d0c
6
+ metadata.gz: e473d6f5f690de91f62283db0364e3a304077dd3445b924a9636a7691593d8d7abf715d5e1ccd7838364a85d4e8611bc4c7d6ab1195b5f0c30d24e32a9d6946c
7
+ data.tar.gz: 84f629bd1dce5dc09637fec05c46d8f78d018b7f89adc4b7a945e50f3edc0cc2077733ca74b41b92e5afb02876f25168b6e40832cf40bebe5c9b63d53fe6a9ac
data/CHANGELOG.md ADDED
@@ -0,0 +1,232 @@
1
+ # Faraday Changelog
2
+
3
+ ## v0.17.3
4
+
5
+ Fixes:
6
+
7
+ * Reverts changes in error classes hierarchy. #1092 (@iMacTia)
8
+ * Fix Ruby 1.9 syntax errors and improve Error class testing #1094 (@BanzaiMan,
9
+ @mrexox, @technoweenie)
10
+
11
+ Misc:
12
+
13
+ * Stops using `&Proc.new` for block forwarding. #1083 (@olleolleolle)
14
+ * Update CI to test against ruby 2.0-2.7 #1087, #1099 (@iMacTia, @olleolleolle,
15
+ @technoweenie)
16
+ * require FARADAY_DEPRECATE=warn to show Faraday v1.0 deprecation warnings
17
+ #1098 (@technoweenie)
18
+
19
+ ## v0.17.1
20
+
21
+ Final release before Faraday v1.0, with important fixes for Ruby 2.7.
22
+
23
+ Fixes:
24
+
25
+ * RaiseError response middleware raises exception if HTTP client returns a nil
26
+ status. #1042 (@jonnyom, @BobbyMcWho)
27
+
28
+ Misc:
29
+
30
+ * Fix Ruby 2.7 warnings (#1009)
31
+ * Add `Faraday::Deprecate` to warn about upcoming v1.0 changes. (#1054, #1059,
32
+ #1076, #1077)
33
+ * Add release notes up to current in CHANGELOG.md (#1066)
34
+ * Port minimal rspec suite from main branch to run backported tests. (#1058)
35
+
36
+ ## v0.17.0
37
+
38
+ This release is the same as v0.15.4. It was pushed to cover up releases
39
+ v0.16.0-v0.16.2.
40
+
41
+ ## v0.15.4
42
+
43
+ * Expose `pool_size` as a option for the NetHttpPersistent adapter (#834)
44
+
45
+ ## v0.15.3
46
+
47
+ * Make Faraday::Request serialisable with Marshal. (#803)
48
+ * Add DEFAULT_EXCEPTIONS constant to Request::Retry (#814)
49
+ * Add support for Ruby 2.6 Net::HTTP write_timeout (#824)
50
+
51
+ ## v0.15.2
52
+
53
+ * Prevents `Net::HTTP` adapters to retry request internally by setting `max_retries` to 0 if available (Ruby 2.5+). (#799)
54
+ * Fixes `NestedParamsEncoder` handling of empty array values (#801)
55
+
56
+ ## v0.15.1
57
+
58
+ * NetHttpPersistent adapter better reuse of SSL connections (#793)
59
+ * Refactor: inline cached_connection (#797)
60
+ * Logger middleware: use $stdout instead of STDOUT (#794)
61
+ * Fix: do not memoize/reuse Patron session (#796)
62
+
63
+ Also in this release:
64
+
65
+ * Allow setting min/max ssl version for Net::HTTP (#792)
66
+ * Allow setting min/max ssl version for Excon (#795)
67
+
68
+ ## v0.15.0
69
+
70
+ Features:
71
+
72
+ * Added retry block option to retry middleware. (#770)
73
+ * Retry middleware improvements (honour Retry-After header, retry statuses) (#773)
74
+ * Improve response logger middleware output (#784)
75
+
76
+ Fixes:
77
+
78
+ * Remove unused class error (#767)
79
+ * Fix minor typo in README (#760)
80
+ * Reuse persistent connections when using net-http-persistent (#778)
81
+ * Fix Retry middleware documentation (#781)
82
+ * Returns the http response when giving up on retrying by status (#783)
83
+
84
+ ## v0.14.0
85
+
86
+ Features:
87
+
88
+ * Allow overriding env proxy (#754)
89
+ * Remove legacy Typhoeus adapter (#715)
90
+ * External Typhoeus Adapter Compatibility (#748)
91
+ * Warn about missing adapter when making a request (#743)
92
+ * Faraday::Adapter::Test stubs now support entire urls (with host) (#741)
93
+
94
+ Fixes:
95
+
96
+ * If proxy is manually provided, this takes priority over `find_proxy` (#724)
97
+ * Fixes the behaviour for Excon's open_timeout (not setting write_timeout anymore) (#731)
98
+ * Handle all connection timeout messages in Patron (#687)
99
+
100
+ ## v0.13.1
101
+
102
+ * Fixes an incompatibility with Addressable::URI being used as uri_parser
103
+
104
+ ## v0.13.0
105
+
106
+ Features:
107
+
108
+ * Dynamically reloads the proxy when performing a request on an absolute domain (#701)
109
+ * Adapter support for Net::HTTP::Persistent v3.0.0 (#619)
110
+
111
+ Fixes:
112
+
113
+ * Prefer #hostname over #host. (#714)
114
+ * Fixes an edge-case issue with response headers parsing (missing HTTP header) (#719)
115
+
116
+ ## v0.12.2
117
+
118
+ * Parse headers from aggregated proxy requests/responses (#681)
119
+ * Guard against invalid middleware configuration with warning (#685)
120
+ * Do not use :insecure option by default in Patron (#691)
121
+ * Fixes an issue with HTTPClient not raising a `Faraday::ConnectionFailed` (#702)
122
+ * Fixes YAML serialization/deserialization for `Faraday::Utils::Headers` (#690)
123
+ * Fixes an issue with Options having a nil value (#694)
124
+ * Fixes an issue with Faraday.default_connection not using Faraday.default_connection_options (#698)
125
+ * Fixes an issue with Options.merge! and Faraday instrumentation middleware (#710)
126
+
127
+ ## v0.12.1
128
+
129
+ * Fix an issue with Patron tests failing on jruby
130
+ * Fix an issue with new `rewind_files` feature that was causing an exception when the body was not an Hash
131
+ * Expose wrapped_exception in all client errors
132
+ * Add Authentication Section to the ReadMe
133
+
134
+ ## v0.12.0.1
135
+
136
+ * Hotfix release to address an issue with TravisCI deploy on Rubygems
137
+
138
+ ## v0.12.0
139
+
140
+ Features:
141
+
142
+ * Proxy feature now relies on Ruby `URI::Generic#find_proxy` and can use `no_proxy` ENV variable (not compatible with ruby < 2.0)
143
+ * Adds support for `context` request option to pass arbitrary information to middlewares
144
+
145
+ Fixes:
146
+
147
+ * Fix an issue with options that was causing new options to override defaults ones unexpectedly
148
+ * Rewind `UploadIO`s on retry to fix a compatibility issue
149
+ * Make multipart boundary unique
150
+ * Improvements in `README.md`
151
+
152
+ ## v0.11.0
153
+
154
+ Features:
155
+
156
+ * Add `filter` method to Logger middleware
157
+ * Add support for Ruby2.4 and Minitest 6
158
+ * Introduce block syntax to customise the adapter
159
+
160
+ Fixes:
161
+
162
+ * Fix an issue that was allowing to override `default_connection_options` from a connection instance
163
+ * Fix a bug that was causing newline escape characters ("\n") to be used when building the Authorization header
164
+
165
+ ## v0.10.1
166
+
167
+ - Fix an issue with HTTPClient adapter that was causing the SSL to be reset on every request
168
+ - Rescue `IOError` instead of specific subclass
169
+ - `Faraday::Utils::Headers` can now be successfully serialised in YAML
170
+ - Handle `default_connection_options` set with hash
171
+
172
+ ## v0.10.0
173
+
174
+ Breaking changes:
175
+ - Drop support for Ruby 1.8
176
+
177
+ Features:
178
+ - Include wrapped exception/reponse in ClientErrors
179
+ - Add `response.reason_phrase`
180
+ - Provide option to selectively skip logging request/response headers
181
+ - Add regex support for pattern matching in `test` adapter
182
+
183
+ Fixes:
184
+ - Add `Faraday.respond_to?` to find methods managed by `method_missing`
185
+ - em-http: `request.host` instead of `connection.host` should be taken for SSL validations
186
+ - Allow `default_connection_options` to be merged when options are passed as url parameter
187
+ - Improve splitting key-value pairs in raw HTTP headers
188
+
189
+ ## v0.9.2
190
+
191
+ Adapters:
192
+ - Enable gzip compression for httpclient
193
+ - Fixes default certificate store for httpclient not having default paths.
194
+ - Make excon adapter compatible with 0.44 excon version
195
+ - Add compatibility with Patron 0.4.20
196
+ - Determine default port numbers in Net::HTTP adapters (Addressable compatibility)
197
+ - em-http: wrap "connection closed by server" as ConnectionFailed type
198
+ - Wrap Errno::ETIMEDOUT in Faraday::Error::TimeoutError
199
+
200
+ Utils:
201
+ - Add Rack-compatible support for parsing `a[][b]=c` nested queries
202
+ - Encode nil values in queries different than empty strings. Before: `a=`; now: `a`.
203
+ - Have `Faraday::Utils::Headers#replace` clear internal key cache
204
+ - Dup the internal key cache when a Headers hash is copied
205
+
206
+ Env and middleware:
207
+ - Ensure `env` stored on middleware response has reference to the response
208
+ - Ensure that Response properties are initialized during `on_complete` (VCR compatibility)
209
+ - Copy request options in Faraday::Connection#dup
210
+ - Env custom members should be copied by Env.from(env)
211
+ - Honour per-request `request.options.params_encoder`
212
+ - Fix `interval_randomness` data type for Retry middleware
213
+ - Add maximum interval option for Retry middleware
214
+
215
+ ## v0.9.1
216
+
217
+ * Refactor Net:HTTP adapter so that with_net_http_connection can be overridden to allow pooled connections. (@Ben-M)
218
+ * Add configurable methods that bypass `retry_if` in the Retry request middleware. (@mike-bourgeous)
219
+
220
+ ## v0.9.0
221
+
222
+ * Add HTTPClient adapter (@hakanensari)
223
+ * Improve Retry handler (@mislav)
224
+ * Remove autoloading by default (@technoweenie)
225
+ * Improve internal docs (@technoweenie, @mislav)
226
+ * Respect user/password in http proxy string (@mislav)
227
+ * Adapter options are structs. Reinforces consistent options across adapters
228
+ (@technoweenie)
229
+ * Stop stripping trailing / off base URLs in a Faraday::Connection. (@technoweenie)
230
+ * Add a configurable URI parser. (@technoweenie)
231
+ * Remove need to manually autoload when using the authorization header helpers on `Faraday::Connection`. (@technoweenie)
232
+ * `Faraday::Adapter::Test` respects the `Faraday::RequestOptions#params_encoder` option. (@technoweenie)
data/LICENSE.md CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2009-2019 Rick Olson, Zack Hobson
1
+ Copyright (c) 2009-2017 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,32 +1,367 @@
1
- # ![Faraday](./docs/assets/img/repo-card-slim.png)
1
+ # Faraday
2
2
 
3
3
  [![Gem Version](https://badge.fury.io/rb/faraday.svg)](https://rubygems.org/gems/faraday)
4
- [![CircleCI](https://circleci.com/gh/lostisland/faraday/tree/master.svg?style=svg)](https://circleci.com/gh/lostisland/faraday/tree/master)
5
- [![Test Coverage](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/test_coverage)](https://codeclimate.com/github/lostisland/faraday/test_coverage)
6
- [![Maintainability](https://api.codeclimate.com/v1/badges/f869daab091ceef1da73/maintainability)](https://codeclimate.com/github/lostisland/faraday/maintainability)
4
+ [![Build Status](https://travis-ci.org/lostisland/faraday.svg?branch=master)](https://travis-ci.org/lostisland/faraday)
5
+ [![Coverage Status](https://coveralls.io/repos/github/lostisland/faraday/badge.svg?branch=master)](https://coveralls.io/github/lostisland/faraday?branch=master)
6
+ [![Code Climate](https://codeclimate.com/github/lostisland/faraday/badges/gpa.svg)](https://codeclimate.com/github/lostisland/faraday)
7
7
  [![Gitter](https://badges.gitter.im/lostisland/faraday.svg)](https://gitter.im/lostisland/faraday?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
8
8
 
9
9
 
10
- Faraday is an HTTP client library that provides a common interface over many
10
+ Faraday is an HTTP client lib 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
- ## Getting Started
14
+ Faraday supports these adapters out of the box:
15
15
 
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.
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
+ ```
18
351
 
19
352
  ## Supported Ruby versions
20
353
 
21
- This library aims to support and is [tested against][circle_ci] the following Ruby
354
+ This library aims to support and is [tested against][travis] the following Ruby
22
355
  implementations:
23
356
 
24
- * Ruby 2.3+
357
+ * Ruby 1.9.3+
358
+ * [JRuby][] 1.7+
359
+ * [Rubinius][] 2+
25
360
 
26
361
  If something doesn't work on one of these Ruby versions, it's a bug.
27
362
 
28
363
  This library may inadvertently work (or seem to work) on other Ruby
29
- implementations and versions, however support will only be provided for the versions listed
364
+ implementations, however support will only be provided for the versions listed
30
365
  above.
31
366
 
32
367
  If you would like this library to support another Ruby version, you may
@@ -40,16 +375,21 @@ of a major release, support for that Ruby version may be dropped.
40
375
 
41
376
  Do you want to contribute to Faraday?
42
377
  Open the issues page and check for the `help wanted` label!
43
- But before you start coding, please read our [Contributing Guide][contributing]
378
+ But before you start coding, please read our [Contributing Guide](https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md)
44
379
 
45
380
  ## Copyright
46
- &copy; 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
47
381
 
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
- [circle_ci]: https://circleci.com/gh/lostisland/faraday
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
53
393
  [jruby]: http://jruby.org/
54
394
  [rubinius]: http://rubini.us/
55
395
  [license]: LICENSE.md
data/Rakefile ADDED
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'rake/testtask'
4
+ require 'rspec/core/rake_task'
5
+
6
+ RSpec::Core::RakeTask.new(:spec)
7
+
8
+ task :default => :test
9
+
10
+ desc "Run all tests"
11
+ task :test => :spec do
12
+ exec 'script/test'
13
+ end