From 59811d75855e5dc3dad853bb0b0f223705d253f6 Mon Sep 17 00:00:00 2001 From: Peter Cai <222655+pcai@users.noreply.github.com> Date: Wed, 10 Jul 2024 16:19:05 +0000 Subject: [PATCH] faraday upgrade docs --- UPGRADING.md | 48 ++++++++++++++++++++++++++++++++++++ lib/savon.rb | 2 +- lib/savon/operation.rb | 2 +- lib/savon/options.rb | 2 +- spec/savon/client_spec.rb | 2 +- spec/savon/observers_spec.rb | 4 +-- spec/savon/options_spec.rb | 7 ++---- spec/savon/request_spec.rb | 4 +-- spec/spec_helper.rb | 4 --- 9 files changed, 58 insertions(+), 17 deletions(-) create mode 100644 UPGRADING.md diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 00000000..439abee7 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,48 @@ +# Upgrading from v2.x to v3.x + +Savon 3 is a major release that 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 result 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" +``` + diff --git a/lib/savon.rb b/lib/savon.rb index 00508a03..072524dd 100644 --- a/lib/savon.rb +++ b/lib/savon.rb @@ -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 diff --git a/lib/savon/operation.rb b/lib/savon/operation.rb index 9a6d3c7f..b28a806d 100644 --- a/lib/savon/operation.rb +++ b/lib/savon/operation.rb @@ -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 diff --git a/lib/savon/options.rb b/lib/savon/options.rb index 974c12e6..4a3c78be 100644 --- a/lib/savon/options.rb +++ b/lib/savon/options.rb @@ -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 diff --git a/spec/savon/client_spec.rb b/spec/savon/client_spec.rb index 869f5b14..e7e5b3a6 100644 --- a/spec/savon/client_spec.rb +++ b/spec/savon/client_spec.rb @@ -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) diff --git a/spec/savon/observers_spec.rb b/spec/savon/observers_spec.rb index 4aeec787..7895a896 100644 --- a/spec/savon/observers_spec.rb +++ b/spec/savon/observers_spec.rb @@ -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(*) @@ -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 diff --git a/spec/savon/options_spec.rb b/spec/savon/options_spec.rb index a6be4d18..5049b1a6 100644 --- a/spec/savon/options_spec.rb +++ b/spec/savon/options_spec.rb @@ -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 @@ -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) @@ -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 diff --git a/spec/savon/request_spec.rb b/spec/savon/request_spec.rb index 12b7f310..3c20a4f7 100644 --- a/spec/savon/request_spec.rb +++ b/spec/savon/request_spec.rb @@ -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) @@ -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 diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 50fc7097..3d9dba13 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -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 }