Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Faraday upgrade docs #1009

Merged
merged 3 commits into from
Jul 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Heavy metal SOAP client
[![Code Climate](https://codeclimate.com/github/savonrb/savon.svg)](https://codeclimate.com/github/savonrb/savon)
[![Coverage Status](https://coveralls.io/repos/savonrb/savon/badge.svg)](https://coveralls.io/r/savonrb/savon)

If you're reading this on GitHub, note that this README is for the main branch and that features/changes described here might not correspond to your version. You can find the documentation for your release [at rubydoc.info](https://www.rubydoc.info/find/gems?q=savon).

## Installation

Expand Down Expand Up @@ -52,6 +53,10 @@ response.body
For more examples, you should check out the
[integration tests](https://github.com/savonrb/savon/tree/version2/spec/integration).

## Upgrading from v2.x to v3.x

See [UPGRADING.md](UPGRADING.md) for more information.

## Ruby version support

Every savon release is tested with contemporary supported versions of ruby. Historical compatibility information:
Expand Down
64 changes: 64 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Upgrading from v2.x to v3.x

Savon 3 replaces its HTTP transport client, [HTTPI](https://github.com/savonrb/httpi) with [Faraday](https://lostisland.github.io/faraday), introducing major breaking changes.

While this brings significant new features and improvements, it also removes or changes some existing features and options.

## Removed Options

### ssl_cert_key_file, ssl_cert_key_password, ssl_cert_file, ssl_ca_cert

These options are no longer supported, as Faraday does not directly support them, and attempting to use them will raise an error.

Resolution:

For `ssl_cert_key_file` and `ssl_cert_key_password` open and decrypt the client key using OpenSSL, and provide the `OpenSSL::PKey::RSA, OpenSSL::PKey::DSA` as the `ssl_cert_key` option instead.

For `ssl_cert_file` pass the `OpenSSL::X509::Certificate` as the `ssl_cert` option instead.

For `ssl_ca_cert` pass the file as the `ssl_ca_cert_file` option instead.

For more information please see https://lostisland.github.io/faraday/#/customization/ssl-options

### ssl_ciphers

Specifying SSL ciphers is no longer supported, as Faraday does not support this, and attempting to use this option will raise an error.

Resolution: remove code that attempts to set `ssl_ciphers`.

### digest_auth

Digest authentication is no longer natively supported. If you need to use it, consider [Faraday::DigestAuth](https://github.com/bhaberer/faraday-digestauth)

## Changed options

### cookies

The `cookies` option now distinguishes between empty and nil string values. If you want to send an empty cookie, you must now set it to an empty string, rather than nil. Nil is reserved for cookie flags like `HttpOnly` or `Secure`. For example:

```ruby
cookies({accept: 'application/json', 'some-cookie': 'foo', "empty-cookie": "", HttpOnly: nil})
```

will send the following cookies:

```
"accept=application/json; some-cookie=foo; empty-cookie=; HttpOnly"
```


### adapters
Savon's adapters option now forwards adapter names and options to faraday.
While not fully supported or tested, it can be used to specify a custom adapter to use. Must be
compliant with faraday's adapter api.

https://lostisland.github.io/faraday/#/adapters/index

For example
```ruby
client = Savon.client(
wsdl: "http://example.com?wsdl",
adapter: [:typhoeus, {connect_timeout: 10}]
)
```
Would create a savon client using the typhoeus adapter with a connect_timeout of 10 seconds.
2 changes: 1 addition & 1 deletion lib/savon.rb
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ class DeprecatedOptionError < Error
attr_accessor :option
def initialize(option)
@option = option
super("#{option} is deprecated as it is not supported in Faraday")
super("#{option} is deprecated as it is not supported in Faraday. See https://github.com/savonrb/savon/blob/main/UPGRADING.md for more information.")
end
end

Expand Down
2 changes: 1 addition & 1 deletion lib/savon/operation.rb
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ def endpoint
end

def raise_expected_faraday_response!
raise Error, "Observers need to return an Faraday::Response to mock " \
raise Error, "Observers need to return a Faraday::Response to mock " \
"the request or nil to execute the request."
end

Expand Down
2 changes: 1 addition & 1 deletion lib/savon/options.rb
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,7 @@ def multipart(multipart)
@options[:multipart] = multipart
end

# Instruct Savon what HTTPI adapter it should use instead of default
# Instruct Savon what Faraday adapter it should use instead of default
def adapter(adapter)
@options[:adapter] = adapter
end
Expand Down
2 changes: 1 addition & 1 deletion spec/savon/client_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
expect(client.globals[:wsdl]).to eq(Fixture.wsdl(:authentication))
end

it "builds an HTTPI request for Wasabi" do
it "builds a Faraday request for Wasabi" do
http_request = mock
wsdl_request = mock(:build => http_request)
Savon::WSDLRequest.expects(:new).with(instance_of(Savon::GlobalOptions)).returns(wsdl_request)
Expand Down
4 changes: 2 additions & 2 deletions spec/savon/observers_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ def notify(*)
expect(response.http.body).to eq("valid!")
end

it "raises if an observer returns something other than nil or an HTTPI::Response" do
it "raises if an observer returns something other than nil or a Faraday::Response" do
observer = Class.new {

def notify(*)
Expand All @@ -77,7 +77,7 @@ def notify(*)
Savon.observers << observer

expect { new_client.call(:authenticate) }.
to raise_error(Savon::Error, "Observers need to return an Faraday::Response " \
to raise_error(Savon::Error, "Observers need to return a Faraday::Response " \
"to mock the request or nil to execute the request.")
end
end
Expand Down
7 changes: 2 additions & 5 deletions spec/savon/options_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -167,11 +167,8 @@
warn "Warning: looks like your network may be down?!\n" +
"-> skipping spec at #{__FILE__}:#{__LINE__}"
else
# TODO: make HTTPI tag timeout errors, then depend on HTTPI::TimeoutError
# instead of a specific client error [dh, 2012-12-08]
expect(Time.now - start_time).to be_within(0.5).of(open_timeout)
expect(error).to be_an(Faraday::ConnectionFailed)

end
}
end
Expand Down Expand Up @@ -333,7 +330,7 @@ def to_s
expect(stdout.string).to be_empty
end

it "silences HTTPI as well" do
it "silences Faraday as well" do
Faraday::Connection.any_instance.expects(:response).with(:logger, nil, {:headers => true, :level => 0}).never

new_client(:log => false)
Expand All @@ -348,7 +345,7 @@ def to_s
expect(stdout.string).to include("INFO -- : SOAP request")
end

it "turns HTTPI logging back on as well" do
it "turns Faraday logging back on as well" do
Faraday::Connection.any_instance.expects(:response).with(:logger, nil, {:headers => true, :level => 0}).at_least_once
new_client(:log => true)
end
Expand Down
4 changes: 2 additions & 2 deletions spec/savon/request_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ def new_wsdl_request
end

describe "build" do
it "returns an Faraday::Request" do
it "returns a Faraday::Request" do
wsdl_request = Savon::WSDLRequest.new(globals)
result = wsdl_request.build
expect(result).to be_an(Faraday::Connection)
Expand Down Expand Up @@ -193,7 +193,7 @@ def new_soap_request
end

describe "build" do
it "returns an Faraday::Request" do
it "returns a Faraday::Request" do
soap_request = Savon::SOAPRequest.new(globals)
expect(soap_request.build).to be_an(Faraday::Connection)
end
Expand Down
4 changes: 0 additions & 4 deletions spec/spec_helper.rb
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,6 @@
require "savon"
require "rspec"

# don't have HTTPI lazy-load HTTPClient, because then
# it can't actually be refered to inside the specs.
require "httpclient"

support_files = File.expand_path("spec/support/**/*.rb")
Dir[support_files].sort.each { |file| require file }

Expand Down