faraday 0.17.4 → 1.0.0.pre.rc1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (88) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE.md +1 -1
  3. data/README.md +18 -358
  4. data/lib/faraday.rb +93 -174
  5. data/lib/faraday/adapter.rb +36 -22
  6. data/lib/faraday/adapter/em_http.rb +142 -99
  7. data/lib/faraday/adapter/em_http_ssl_patch.rb +23 -17
  8. data/lib/faraday/adapter/em_synchrony.rb +104 -60
  9. data/lib/faraday/adapter/em_synchrony/parallel_manager.rb +18 -15
  10. data/lib/faraday/adapter/excon.rb +97 -57
  11. data/lib/faraday/adapter/httpclient.rb +61 -39
  12. data/lib/faraday/adapter/net_http.rb +103 -51
  13. data/lib/faraday/adapter/net_http_persistent.rb +49 -28
  14. data/lib/faraday/adapter/patron.rb +54 -35
  15. data/lib/faraday/adapter/rack.rb +28 -12
  16. data/lib/faraday/adapter/test.rb +86 -53
  17. data/lib/faraday/adapter/typhoeus.rb +4 -1
  18. data/lib/faraday/adapter_registry.rb +28 -0
  19. data/lib/faraday/autoload.rb +47 -36
  20. data/lib/faraday/connection.rb +321 -179
  21. data/lib/faraday/dependency_loader.rb +37 -0
  22. data/lib/faraday/encoders/flat_params_encoder.rb +94 -0
  23. data/lib/faraday/encoders/nested_params_encoder.rb +171 -0
  24. data/lib/faraday/error.rb +21 -79
  25. data/lib/faraday/logging/formatter.rb +92 -0
  26. data/lib/faraday/middleware.rb +4 -28
  27. data/lib/faraday/middleware_registry.rb +129 -0
  28. data/lib/faraday/options.rb +33 -184
  29. data/lib/faraday/options/connection_options.rb +22 -0
  30. data/lib/faraday/options/env.rb +181 -0
  31. data/lib/faraday/options/proxy_options.rb +28 -0
  32. data/lib/faraday/options/request_options.rb +21 -0
  33. data/lib/faraday/options/ssl_options.rb +59 -0
  34. data/lib/faraday/parameters.rb +4 -197
  35. data/lib/faraday/rack_builder.rb +66 -55
  36. data/lib/faraday/request.rb +68 -36
  37. data/lib/faraday/request/authorization.rb +42 -30
  38. data/lib/faraday/request/basic_authentication.rb +14 -7
  39. data/lib/faraday/request/instrumentation.rb +45 -27
  40. data/lib/faraday/request/multipart.rb +72 -49
  41. data/lib/faraday/request/retry.rb +197 -171
  42. data/lib/faraday/request/token_authentication.rb +15 -10
  43. data/lib/faraday/request/url_encoded.rb +41 -23
  44. data/lib/faraday/response.rb +22 -15
  45. data/lib/faraday/response/logger.rb +22 -69
  46. data/lib/faraday/response/raise_error.rb +36 -18
  47. data/lib/faraday/upload_io.rb +29 -18
  48. data/lib/faraday/utils.rb +28 -245
  49. data/lib/faraday/utils/headers.rb +139 -0
  50. data/lib/faraday/utils/params_hash.rb +61 -0
  51. data/spec/external_adapters/faraday_specs_setup.rb +14 -0
  52. metadata +25 -51
  53. data/CHANGELOG.md +0 -232
  54. data/Rakefile +0 -13
  55. data/lib/faraday/deprecate.rb +0 -109
  56. data/spec/faraday/deprecate_spec.rb +0 -147
  57. data/spec/faraday/error_spec.rb +0 -102
  58. data/spec/faraday/response/raise_error_spec.rb +0 -106
  59. data/spec/spec_helper.rb +0 -105
  60. data/test/adapters/default_test.rb +0 -14
  61. data/test/adapters/em_http_test.rb +0 -30
  62. data/test/adapters/em_synchrony_test.rb +0 -32
  63. data/test/adapters/excon_test.rb +0 -30
  64. data/test/adapters/httpclient_test.rb +0 -34
  65. data/test/adapters/integration.rb +0 -263
  66. data/test/adapters/logger_test.rb +0 -136
  67. data/test/adapters/net_http_persistent_test.rb +0 -114
  68. data/test/adapters/net_http_test.rb +0 -79
  69. data/test/adapters/patron_test.rb +0 -40
  70. data/test/adapters/rack_test.rb +0 -38
  71. data/test/adapters/test_middleware_test.rb +0 -157
  72. data/test/adapters/typhoeus_test.rb +0 -38
  73. data/test/authentication_middleware_test.rb +0 -65
  74. data/test/composite_read_io_test.rb +0 -109
  75. data/test/connection_test.rb +0 -738
  76. data/test/env_test.rb +0 -268
  77. data/test/helper.rb +0 -75
  78. data/test/live_server.rb +0 -67
  79. data/test/middleware/instrumentation_test.rb +0 -88
  80. data/test/middleware/retry_test.rb +0 -282
  81. data/test/middleware_stack_test.rb +0 -260
  82. data/test/multibyte.txt +0 -1
  83. data/test/options_test.rb +0 -333
  84. data/test/parameters_test.rb +0 -157
  85. data/test/request_middleware_test.rb +0 -126
  86. data/test/response_middleware_test.rb +0 -72
  87. data/test/strawberry.rb +0 -2
  88. 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: 796572c71fdcd51b8c208072304ac74f0c408fece78878a69b1a1abb55a10939
4
+ data.tar.gz: 3eea5a3f432b1979e6419dd5445507425a5859c53b3c7f62f14ad9d55cbbf787
5
5
  SHA512:
6
- metadata.gz: e473d6f5f690de91f62283db0364e3a304077dd3445b924a9636a7691593d8d7abf715d5e1ccd7838364a85d4e8611bc4c7d6ab1195b5f0c30d24e32a9d6946c
7
- data.tar.gz: 84f629bd1dce5dc09637fec05c46d8f78d018b7f89adc4b7a945e50f3edc0cc2077733ca74b41b92e5afb02876f25168b6e40832cf40bebe5c9b63d53fe6a9ac
6
+ metadata.gz: 2ee806bf77a77b00b17c75644123b6c2eada90e1d096df5a5c21b588608133dfacbe74049a82c4980452e1155d03fcc2b1ceca131dcd5a349e131aa6aca44a08
7
+ data.tar.gz: 147ad4806869e58ffe5e68936d1abe2559ead47b971441c57b47b930df3c74780c5d131c1d180bf2b74cac34df70628ebed3296e1fd4367ce46c87d98849047f
data/LICENSE.md CHANGED
@@ -1,4 +1,4 @@
1
- Copyright (c) 2009-2017 Rick Olson, Zack Hobson
1
+ Copyright (c) 2009-2019 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,32 @@
1
- # Faraday
1
+ # ![Faraday](./docs/assets/img/repo-card-slim.png)
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
+ [![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)
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 lib that provides a common interface over many
10
+ Faraday is an HTTP client library that provides a common interface over many
11
11
  adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
12
12
  processing the request/response cycle.
13
13
 
14
- Faraday supports these adapters out of the box:
14
+ ## Getting Started
15
15
 
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
- ```
16
+ The best starting point is the [Faraday Website][website], with its introduction and explanation.
17
+ Need more details? See the [Faraday API Documentation][apidoc] to see how it works internally.
351
18
 
352
19
  ## Supported Ruby versions
353
20
 
354
- This library aims to support and is [tested against][travis] the following Ruby
21
+ This library aims to support and is [tested against][circle_ci] the following Ruby
355
22
  implementations:
356
23
 
357
- * Ruby 1.9.3+
358
- * [JRuby][] 1.7+
359
- * [Rubinius][] 2+
24
+ * Ruby 2.3+
360
25
 
361
26
  If something doesn't work on one of these Ruby versions, it's a bug.
362
27
 
363
28
  This library may inadvertently work (or seem to work) on other Ruby
364
- implementations, however support will only be provided for the versions listed
29
+ implementations and versions, however support will only be provided for the versions listed
365
30
  above.
366
31
 
367
32
  If you would like this library to support another Ruby version, you may
@@ -375,21 +40,16 @@ of a major release, support for that Ruby version may be dropped.
375
40
 
376
41
  Do you want to contribute to Faraday?
377
42
  Open the issues page and check for the `help wanted` label!
378
- But before you start coding, please read our [Contributing Guide](https://github.com/lostisland/faraday/blob/master/.github/CONTRIBUTING.md)
43
+ But before you start coding, please read our [Contributing Guide][contributing]
379
44
 
380
45
  ## Copyright
46
+ © 2009 - 2019, the [Faraday Team][faraday_team]. Website and branding design by [Elena Lo Piccolo](https://elelopic.design).
381
47
 
382
- 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
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
393
53
  [jruby]: http://jruby.org/
394
54
  [rubinius]: http://rubini.us/
395
55
  [license]: LICENSE.md
data/lib/faraday.rb CHANGED
@@ -1,128 +1,153 @@
1
- require 'thread'
1
+ # frozen_string_literal: true
2
+
2
3
  require 'cgi'
3
4
  require 'set'
4
5
  require 'forwardable'
6
+ require 'faraday/middleware_registry'
7
+ require 'faraday/dependency_loader'
5
8
 
6
- # Public: This is the main namespace for Faraday. You can either use it to
7
- # create Faraday::Connection objects, or access it directly.
9
+ # This is the main namespace for Faraday.
8
10
  #
9
- # Examples
11
+ # It provides methods to create {Connection} objects, and HTTP-related
12
+ # methods to use directly.
10
13
  #
14
+ # @example Helpful class methods for easy usage
11
15
  # Faraday.get "http://faraday.com"
12
16
  #
17
+ # @example Helpful class method `.new` to create {Connection} objects.
13
18
  # conn = Faraday.new "http://faraday.com"
14
19
  # conn.get '/'
15
20
  #
16
21
  module Faraday
17
- VERSION = "0.17.4"
22
+ VERSION = '1.0.0-rc1'
23
+ METHODS_WITH_QUERY = %w[get head delete connect trace].freeze
24
+ METHODS_WITH_BODY = %w[post put patch].freeze
18
25
 
19
26
  class << self
20
- # Public: Gets or sets the root path that Faraday is being loaded from.
21
- # This is the root from where the libraries are auto-loaded from.
27
+ # The root path that Faraday is being loaded from.
28
+ #
29
+ # This is the root from where the libraries are auto-loaded.
30
+ #
31
+ # @return [String]
22
32
  attr_accessor :root_path
23
33
 
24
- # Public: Gets or sets the path that the Faraday libs are loaded from.
34
+ # Gets or sets the path that the Faraday libs are loaded from.
35
+ # @return [String]
25
36
  attr_accessor :lib_path
26
37
 
27
- # Public: Gets or sets the Symbol key identifying a default Adapter to use
28
- # for the default Faraday::Connection.
38
+ # @overload default_adapter
39
+ # Gets the Symbol key identifying a default Adapter to use
40
+ # for the default {Faraday::Connection}. Defaults to `:net_http`.
41
+ # @return [Symbol] the default adapter
42
+ # @overload default_adapter=(adapter)
43
+ # Updates default adapter while resetting {.default_connection}.
44
+ # @return [Symbol] the new default_adapter.
29
45
  attr_reader :default_adapter
30
46
 
31
- # Public: Sets the default Faraday::Connection for simple scripts that
32
- # access the Faraday constant directly.
33
- #
34
- # Faraday.get "https://faraday.com"
47
+ # Documented below, see default_connection
35
48
  attr_writer :default_connection
36
49
 
37
- # Public: Tells faraday to ignore the environment proxy (http_proxy).
50
+ # Tells Faraday to ignore the environment proxy (http_proxy).
51
+ # Defaults to `false`.
52
+ # @return [Boolean]
38
53
  attr_accessor :ignore_env_proxy
39
54
 
40
- # Public: Initializes a new Faraday::Connection.
41
- #
42
- # url - The optional String base URL to use as a prefix for all
43
- # requests. Can also be the options Hash.
44
- # options - The optional Hash used to configure this Faraday::Connection.
45
- # Any of these values will be set on every request made, unless
46
- # overridden for a specific request.
47
- # :url - String base URL.
48
- # :params - Hash of URI query unencoded key/value pairs.
49
- # :headers - Hash of unencoded HTTP header key/value pairs.
50
- # :request - Hash of request options.
51
- # :ssl - Hash of SSL options.
52
- # :proxy - Hash of Proxy options.
53
- #
54
- # Examples
55
- #
55
+ # Initializes a new {Connection}.
56
+ #
57
+ # @param url [String,Hash] The optional String base URL to use as a prefix
58
+ # for all requests. Can also be the options Hash. Any of these
59
+ # values will be set on every request made, unless overridden
60
+ # for a specific request.
61
+ # @param options [Hash]
62
+ # @option options [String] :url Base URL
63
+ # @option options [Hash] :params Hash of unencoded URI query params.
64
+ # @option options [Hash] :headers Hash of unencoded HTTP headers.
65
+ # @option options [Hash] :request Hash of request options.
66
+ # @option options [Hash] :ssl Hash of SSL options.
67
+ # @option options [Hash] :proxy Hash of Proxy options.
68
+ # @return [Faraday::Connection]
69
+ #
70
+ # @example With an URL argument
56
71
  # Faraday.new 'http://faraday.com'
57
- #
58
- # # http://faraday.com?page=1
59
- # Faraday.new 'http://faraday.com', :params => {:page => 1}
60
- #
61
- # # same
62
- #
63
- # Faraday.new :url => 'http://faraday.com',
64
- # :params => {:page => 1}
65
- #
66
- # Returns a Faraday::Connection.
67
- def new(url = nil, options = nil, &block)
68
- options = options ? default_connection_options.merge(options) : default_connection_options
72
+ # # => Faraday::Connection to http://faraday.com
73
+ #
74
+ # @example With an URL argument and an options hash
75
+ # Faraday.new 'http://faraday.com', params: { page: 1 }
76
+ # # => Faraday::Connection to http://faraday.com?page=1
77
+ #
78
+ # @example With everything in an options hash
79
+ # Faraday.new url: 'http://faraday.com',
80
+ # params: { page: 1 }
81
+ # # => Faraday::Connection to http://faraday.com?page=1
82
+ def new(url = nil, options = {}, &block)
83
+ options = default_connection_options.merge(options)
69
84
  Faraday::Connection.new(url, options, &block)
70
85
  end
71
86
 
87
+ # @private
72
88
  # Internal: Requires internal Faraday libraries.
73
89
  #
74
- # *libs - One or more relative String names to Faraday classes.
75
- #
76
- # Returns nothing.
90
+ # @param libs [Array] one or more relative String names to Faraday classes.
91
+ # @return [void]
77
92
  def require_libs(*libs)
78
93
  libs.each do |lib|
79
94
  require "#{lib_path}/#{lib}"
80
95
  end
81
96
  end
82
97
 
83
- # Public: Updates default adapter while resetting
84
- # #default_connection.
85
- #
86
- # Returns the new default_adapter.
98
+ alias require_lib require_libs
99
+
100
+ # Documented elsewhere, see default_adapter reader
87
101
  def default_adapter=(adapter)
88
102
  @default_connection = nil
89
103
  @default_adapter = adapter
90
104
  end
91
105
 
92
- alias require_lib require_libs
93
-
94
- def respond_to?(symbol, include_private = false)
106
+ def respond_to_missing?(symbol, include_private = false)
95
107
  default_connection.respond_to?(symbol, include_private) || super
96
108
  end
97
109
 
98
- private
110
+ private
111
+
99
112
  # Internal: Proxies method calls on the Faraday constant to
100
- # #default_connection.
113
+ # .default_connection.
101
114
  def method_missing(name, *args, &block)
102
- default_connection.send(name, *args, &block)
115
+ if default_connection.respond_to?(name)
116
+ default_connection.send(name, *args, &block)
117
+ else
118
+ super
119
+ end
103
120
  end
104
121
  end
105
122
 
106
123
  self.ignore_env_proxy = false
107
- self.root_path = File.expand_path "..", __FILE__
108
- self.lib_path = File.expand_path "../faraday", __FILE__
124
+ self.root_path = File.expand_path __dir__
125
+ self.lib_path = File.expand_path 'faraday', __dir__
109
126
  self.default_adapter = :net_http
110
127
 
111
- # Gets the default connection used for simple scripts.
112
- #
113
- # Returns a Faraday::Connection, configured with the #default_adapter.
128
+ # @overload default_connection
129
+ # Gets the default connection used for simple scripts.
130
+ # @return [Faraday::Connection] a connection configured with
131
+ # the default_adapter.
132
+ # @overload default_connection=(connection)
133
+ # @param connection [Faraday::Connection]
134
+ # Sets the default {Faraday::Connection} for simple scripts that
135
+ # access the Faraday constant directly, such as
136
+ # <code>Faraday.get "https://faraday.com"</code>.
114
137
  def self.default_connection
115
138
  @default_connection ||= Connection.new(default_connection_options)
116
139
  end
117
140
 
118
- # Gets the default connection options used when calling Faraday#new.
141
+ # Gets the default connection options used when calling {Faraday#new}.
119
142
  #
120
- # Returns a Faraday::ConnectionOptions.
143
+ # @return [Faraday::ConnectionOptions]
121
144
  def self.default_connection_options
122
145
  @default_connection_options ||= ConnectionOptions.new
123
146
  end
124
147
 
125
- # Public: Sets the default options used when calling Faraday#new.
148
+ # Sets the default options used when calling {Faraday#new}.
149
+ #
150
+ # @param options [Hash, Faraday::ConnectionOptions]
126
151
  def self.default_connection_options=(options)
127
152
  @default_connection = nil
128
153
  @default_connection_options = ConnectionOptions.from(options)
@@ -133,115 +158,9 @@ module Faraday
133
158
  Timer = Timeout
134
159
  end
135
160
 
136
- # Public: Adds the ability for other modules to register and lookup
137
- # middleware classes.
138
- module MiddlewareRegistry
139
- # Public: Register middleware class(es) on the current module.
140
- #
141
- # mapping - A Hash mapping Symbol keys to classes. Classes can be expressed
142
- # as fully qualified constant, or a Proc that will be lazily
143
- # called to return the former.
144
- #
145
- # Examples
146
- #
147
- # module Faraday
148
- # class Whatever
149
- # # Middleware looked up by :foo returns Faraday::Whatever::Foo.
150
- # register_middleware :foo => Foo
151
- #
152
- # # Middleware looked up by :bar returns Faraday::Whatever.const_get(:Bar)
153
- # register_middleware :bar => :Bar
154
- #
155
- # # Middleware looked up by :baz requires 'baz' and returns Faraday::Whatever.const_get(:Baz)
156
- # register_middleware :baz => [:Baz, 'baz']
157
- # end
158
- # end
159
- #
160
- # Returns nothing.
161
- def register_middleware(autoload_path = nil, mapping = nil)
162
- if mapping.nil?
163
- mapping = autoload_path
164
- autoload_path = nil
165
- end
166
- middleware_mutex do
167
- @middleware_autoload_path = autoload_path if autoload_path
168
- (@registered_middleware ||= {}).update(mapping)
169
- end
170
- end
161
+ require_libs 'utils', 'options', 'connection', 'rack_builder', 'parameters',
162
+ 'middleware', 'adapter', 'request', 'response', 'upload_io',
163
+ 'error'
171
164
 
172
- # Public: Lookup middleware class with a registered Symbol shortcut.
173
- #
174
- # key - The Symbol key for the registered middleware.
175
- #
176
- # Examples
177
- #
178
- # module Faraday
179
- # class Whatever
180
- # register_middleware :foo => Foo
181
- # end
182
- # end
183
- #
184
- # Faraday::Whatever.lookup_middleware(:foo)
185
- # # => Faraday::Whatever::Foo
186
- #
187
- # Returns a middleware Class.
188
- def lookup_middleware(key)
189
- load_middleware(key) ||
190
- raise(Faraday::Error.new("#{key.inspect} is not registered on #{self}"))
191
- end
192
-
193
- def middleware_mutex(&block)
194
- @middleware_mutex ||= begin
195
- require 'monitor'
196
- Monitor.new
197
- end
198
- @middleware_mutex.synchronize(&block)
199
- end
200
-
201
- def fetch_middleware(key)
202
- defined?(@registered_middleware) && @registered_middleware[key]
203
- end
204
-
205
- def load_middleware(key)
206
- value = fetch_middleware(key)
207
- case value
208
- when Module
209
- value
210
- when Symbol, String
211
- middleware_mutex do
212
- @registered_middleware[key] = const_get(value)
213
- end
214
- when Proc
215
- middleware_mutex do
216
- @registered_middleware[key] = value.call
217
- end
218
- when Array
219
- middleware_mutex do
220
- const, path = value
221
- if root = @middleware_autoload_path
222
- path = "#{root}/#{path}"
223
- end
224
- require(path)
225
- @registered_middleware[key] = const
226
- end
227
- load_middleware(key)
228
- end
229
- end
230
- end
231
-
232
- def self.const_missing(name)
233
- if name.to_sym == :Builder
234
- warn "Faraday::Builder is now Faraday::RackBuilder."
235
- const_set name, RackBuilder
236
- else
237
- super
238
- end
239
- end
240
-
241
- require_libs "utils", "options", "connection", "rack_builder", "parameters",
242
- "middleware", "adapter", "request", "response", "upload_io", "error"
243
-
244
- if !ENV["FARADAY_NO_AUTOLOAD"]
245
- require_lib 'autoload'
246
- end
165
+ require_lib 'autoload' unless ENV['FARADAY_NO_AUTOLOAD']
247
166
  end