Faraday upgrade docs (#1009)

Co-authored-by: Lucas Ridge <[email protected]>

README.md

@@ -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
 
@@ -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:

UPGRADING.md

@@ -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.

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
 

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
 

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

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)

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

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

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

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 }