UPGRADING.md
With this release, we've officially moved all adapters, except for the net_http one, out of Faraday.
What that means, is that they won't be available out-of-the-box anymore,
and you'll instead need to add them to your Gemfile.
NOTE: the net_http adapter was originally removed as well in version 2.0, but quickly reintroduced in version 2.0.1.
We strongly suggest you to skip version 2.0 and instead use version 2.0.1 or greater.
We've taken this decision for the following technical reasons:
We did our best to make this transition as painless as possible for you, so here is what we did.
net_http one, have already been moved out and released as separate gems.
They've then been re-added into Faraday's v1 dependencies so that you wouldn't notice.
This means that immediately after v2.0 will be released, all the adapters that were previously available will be
already compatible with Faraday 2.0!net_http adapter, then you don't need to do anything!faraday-net_http_persistent). Then, simply require them after you require faraday.
# Gemfile
gem 'faraday'
gem 'faraday-net_http_persistent'
# Code
require 'faraday'
require 'faraday/net_http_persistent'
In case you never used it, Faraday Middleware is a handy collection of middleware that have so far been maintained by the Faraday core team.
With Faraday 2.0 focusing on becoming an ecosystem, rather than an out-of-the-box solution, it only made sense to take the same approach for middleware as we did for adapters. For this reason, faraday_middleware will not be updated to support Faraday 2.0.
Instead, we'll support the transition from centralised-repo collection of middleware to individual middleware gems, effectively replicating what we did with adapters. Each middleware will have its own repository and gem, and it will allow developers to only add the ones they require to their Gemfile.
So don't fret yet! We're doing our best to support our faraday_middleware users out there, so here are the steps we've taken to make this work:
faraday_middleware users will be able to just stop using the extra dependency thanks to this.It will obviously take time for some of the middleware in faraday_middleware to make its way into a separate gem, so we appreciate this might be an upgrade obstacle for some. However this is part of an effort to focus the core team resources tackling the most requested features.
We'll be listening to the community and prioritize middleware that are most used, and will be welcoming contributors who want to become owners of the middleware when these become separate from the faraday_middleware repo.
Moving middleware into its own gem makes sense not only for faraday_middleware, but also for middleware bundled with Faraday.
As of v2.0, the retry and multipart middleware have been moved to separate faraday-retry and faraday-multipart gems.
These have been identified as good candidates due to their complexity and external dependencies.
Thanks to this change, we were able to make Faraday 2.0 completely dependency free 🎉 (the only exception being ruby2_keywords, which will be necessary only while we keep supporting Ruby 2.6).
retry or multipart middleware?Upgrading is pretty simple, because the middleware was simply moved out to external gems.
All you need to do is to add them to your gemfile (either faraday-retry or faraday-multipart and require them before usage:
# Gemfile
gem 'faraday-multipart'
gem 'faraday-retry'
# Connection initializer
require 'faraday/retry'
require 'faraday/multipart'
conn = Faraday.new(url) do |f|
f.request :multipart
f.request :retry
# ...
end
Faraday has until now provided and relied on a complex dynamic dependencies system. This would allow to reference classes and require dependencies only when needed (e.g. when running the first request) based on the middleware/adapters used. As part of Faraday v2.0, we've removed all external dependencies, which means we don't really need this anymore. This change should not affect you directly, but if you're registering middleware then be aware of the new syntax:
# `name` here can be anything you want.
# `klass` is your custom middleware class.
# This method can also be called on `Faraday::Adapter`, `Faraday::Request` and `Faraday::Response`
Faraday::Middleware.register_middleware(name: klass)
The register_middleware method also previously allowed to provide a symbol, string, proc, or array
but this has been removed from the v2.0 release to simplify the interface.
(EDIT: symbol/string/proc have subsequently been reintroduced in v2.2, but not the array).
You were previously able to call authorization, basic_auth and token_auth against the Connection object, but this helper methods have now been dropped.
Instead, you should be using the equivalent middleware, as explained in this page.
For more details, see https://github.com/lostisland/faraday/pull/1306
dependency method in middlewares has been removedIn Faraday 1, a deferred require was used with the dependency method.
In Faraday 2, that method has been removed. In your middleware gems, use a regular require at the top of the file,
Faraday::Request#method to #http_method.Faraday::Response::Middleware. You can now use the new on_complete callback provided by Faraday::Middleware.Faraday.default_connection_options will now be deep-merged into new connections to avoid overriding them (e.g. headers).Faraday::Builder#build method is not exposed through Faraday::Connection anymore and does not reset the handlers if called multiple times. This method should be used internally only.Faraday::Error. A sub-class (e.g. ClientError) was previously accessible
either through the Faraday module (e.g. Faraday::ClientError) or through the Faraday::Error class (e.g. Faraday::Error::ClientError).
The latter is no longer available and the former should be used instead, so check your rescues.Faraday::ServerError (5xx status codes) alongside the existing Faraday::ClientError (4xx status codes).
Please note Faraday::ClientError was previously used for both.Faraday::ConnectionFailed before.If you have written a custom adapter, please be aware that env.body is now an alias to the two new properties request_body and response_body.
This should work without you noticing if your adapter inherits from Faraday::Adapter and calls save_response, but if it doesn't, then please ensure you set the status BEFORE the body while processing the response.
#adapter method on the connection builder. If you don't do so and your adapter inherits from Faraday::Adapter then Faraday will raise an exception. Otherwise, Faraday will automatically push the default adapter at the end of the stack causing your request to be executed twice.class OfficialAdapter < Faraday::Adapter
...
end
class MyAdapter
...
end
# This will raise an exception
conn = Faraday.new(...) do |f|
f.use OfficialAdapter
end
# This will cause Faraday inserting the default adapter at the end of the stack
conn = Faraday.new(...) do |f|
f.use MyAdapter
end
# You MUST use `adapter` method
conn = Faraday.new(...) do |f|
f.adapter AnyAdapter
end