savon 2.16.0 → 2.17.4

data/lib/savon/options.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
+
 require "logger"
 require "httpi"
+require "savon/faraday_migration_hint"
 
 module Savon
+  # Base class for GlobalOptions and LocalOptions.
+  # Stores options in a hash, dispatches setter calls by method name,
+  # raises UnknownOptionError for anything not defined on the subclass.
   class Options
-
     def initialize(options = {})
       @options = {}
       assign options
@@ -18,7 +22,7 @@ module Savon
 
     def []=(option, value)
       value = [value].flatten
-      self.send(option, *value)
+      send(option, *value)
     end
 
     def include?(option)
@@ -29,7 +33,7 @@ module Savon
 
     def assign(options)
       options.each do |option, value|
-        self.send(option, value)
+        send(option, value)
       end
     end
 
@@ -38,6 +42,8 @@ module Savon
     end
   end
 
+  # Options available in both GlobalOptions and LocalOptions.
+  # Currently covers WSSE authentication and timestamp headers.
   module SharedOptions
     # WSSE auth credentials for Akami.
     # Local will override the global wsse_auth value, e.g.
@@ -46,11 +52,12 @@ module Savon
     #   global == [user, pass] && local == nil   => [user, pass]
     def wsse_auth(*credentials)
       credentials.flatten!
-      if credentials.size == 1
-        @options[:wsse_auth] = credentials.first
-      else
-        @options[:wsse_auth] = credentials
-      end
+      @options[:wsse_auth] =
+        if credentials.size == 1
+          credentials.first
+        else
+          credentials
+        end
     end
 
     # Instruct Akami to enable wsu:Timestamp headers.
@@ -67,35 +74,186 @@ module Savon
     end
   end
 
+  # Options that belong to HTTPI's transport layer.
+  #
+  # They still work with the default HTTPI transport. With `transport: :faraday`,
+  # Savon does not translate them because Faraday exposes its own setup API for
+  # proxy, timeout, TLS, auth, redirects, and adapter choices.
+  module HTTPITransportOptions
+    TRANSPORT_DEFAULTS = {
+      adapter: nil,
+      follow_redirects: false
+    }.freeze
+
+    # These are rejected for `transport: :faraday` once the caller has set a
+    # non-default value. The error points to the matching Faraday setup.
+    FARADAY_INCOMPATIBLE_GLOBALS = FaradayMigrationHint::OPTIONS
+
+    # Runs after all global options have been assigned, including options set in
+    # the client block. Reports every HTTPI-only option in one error so callers
+    # can move their transport setup to Faraday in one pass.
+    def validate_transport!
+      return unless self[:transport] == :faraday
+
+      unless faraday_loaded?
+        raise InitializationError,
+              "transport: :faraday requires the faraday gem.\n" \
+              "Add to your Gemfile: gem 'faraday'"
+      end
+
+      violations = FARADAY_INCOMPATIBLE_GLOBALS.filter_map { |option|
+        next unless include?(option)
+        next if default_transport_option?(option)
+
+        FaradayMigrationHint.new(option, self[option]).message
+      }
+
+      return if violations.empty?
+
+      raise InitializationError,
+            "The following options are not supported with transport: :faraday:\n#{violations.join("\n")}"
+    end
+
+    # Proxy server to use for all requests.
+    def proxy(proxy)
+      @options[:proxy] = proxy unless proxy.nil?
+    end
+
+    # Open timeout in seconds.
+    def open_timeout(open_timeout)
+      @options[:open_timeout] = open_timeout
+    end
+
+    # Read timeout in seconds.
+    def read_timeout(read_timeout)
+      @options[:read_timeout] = read_timeout
+    end
+
+    # Write timeout in seconds.
+    def write_timeout(write_timeout)
+      @options[:write_timeout] = write_timeout
+    end
+
+    # Specifies the SSL version to use.
+    def ssl_version(version)
+      @options[:ssl_version] = version
+    end
+
+    # Specifies the minimum SSL version to use.
+    def ssl_min_version(version)
+      @options[:ssl_min_version] = version
+    end
+
+    # Specifies the maximum SSL version to use.
+    def ssl_max_version(version)
+      @options[:ssl_max_version] = version
+    end
+
+    # Whether and how to verify the SSL connection.
+    def ssl_verify_mode(verify_mode)
+      @options[:ssl_verify_mode] = verify_mode
+    end
+
+    # Sets the cert key file to use.
+    def ssl_cert_key_file(file)
+      @options[:ssl_cert_key_file] = file
+    end
+
+    # Sets the cert key to use.
+    def ssl_cert_key(key)
+      @options[:ssl_cert_key] = key
+    end
+
+    # Sets the cert key password to use.
+    def ssl_cert_key_password(password)
+      @options[:ssl_cert_key_password] = password
+    end
+
+    # Sets the cert file to use.
+    def ssl_cert_file(file)
+      @options[:ssl_cert_file] = file
+    end
+
+    # Sets the cert to use.
+    def ssl_cert(cert)
+      @options[:ssl_cert] = cert
+    end
+
+    # Sets the CA cert file to use.
+    def ssl_ca_cert_file(file)
+      @options[:ssl_ca_cert_file] = file
+    end
+
+    # Sets the CA cert to use.
+    def ssl_ca_cert(cert)
+      @options[:ssl_ca_cert] = cert
+    end
+
+    # Sets the SSL ciphers to use.
+    def ssl_ciphers(ciphers)
+      @options[:ssl_ciphers] = ciphers
+    end
+
+    # Sets the CA cert path.
+    def ssl_ca_cert_path(path)
+      @options[:ssl_ca_cert_path] = path
+    end
+
+    # Sets the SSL cert store.
+    def ssl_cert_store(store)
+      @options[:ssl_cert_store] = store
+    end
+
+    # HTTP basic auth credentials.
+    def basic_auth(*credentials)
+      @options[:basic_auth] = credentials.flatten
+    end
+
+    # HTTP digest auth credentials.
+    def digest_auth(*credentials)
+      @options[:digest_auth] = credentials.flatten
+    end
+
+    # NTLM auth credentials.
+    def ntlm(*credentials)
+      @options[:ntlm] = credentials.flatten
+    end
+
+    # Instruct requests to follow HTTP redirects.
+    def follow_redirects(follow_redirects)
+      @options[:follow_redirects] = follow_redirects
+    end
+
+    # Instruct Savon which HTTPI adapter to use instead of the default.
+    def adapter(adapter)
+      @options[:adapter] = adapter
+    end
+
+    private
+
+    def default_transport_option?(option)
+      TRANSPORT_DEFAULTS.key?(option) && self[option] == TRANSPORT_DEFAULTS[option]
+    end
+
+    # Attempts to load faraday. Returns true if available, false on LoadError.
+    def faraday_loaded?
+      require "faraday"
+      true
+    rescue LoadError
+      false
+    end
+  end
+
+  # Client-level options applied to every request made by a Savon::Client instance.
+  # Covers service location, SOAP configuration, logging, response parsing,
+  # and transport selection. HTTPI-specific options (proxy, timeouts, SSL, auth)
+  # come from HTTPITransportOptions.
   class GlobalOptions < Options
     include SharedOptions
+    include HTTPITransportOptions
 
     def initialize(options = {})
       @option_type = :global
-
-      defaults = {
-        :encoding                    => "UTF-8",
-        :soap_version                => 1,
-        :namespaces                  => {},
-        :logger                      => Logger.new($stdout),
-        :log                         => false,
-        :log_headers                 => true,
-        :filters                     => [],
-        :pretty_print_xml            => false,
-        :raise_errors                => true,
-        :strip_namespaces            => true,
-        :delete_namespace_attributes => false,
-        :convert_response_tags_to    => lambda { |tag| StringUtils.snakecase(tag).to_sym},
-        :convert_attributes_to       => lambda { |k,v| [k,v] },
-        :multipart                   => false,
-        :adapter                     => nil,
-        :use_wsa_headers             => false,
-        :no_message_tag              => false,
-        :follow_redirects            => false,
-        :unwrap                      => false,
-        :host                        => nil
-      }
-
       options = defaults.merge(options)
 
       # this option is a shortcut on the logger which needs to be set
@@ -112,7 +270,7 @@ module Savon
       @options[:wsdl] = wsdl_address
     end
 
-    # set different host for actions in WSDL
+    # Set a different host for actions in the WSDL.
     def host(host)
       @options[:host] = host
     end
@@ -127,7 +285,7 @@ module Savon
       @options[:namespace] = namespace
     end
 
-    # The namespace identifer.
+    # The namespace identifier.
     def namespace_identifier(identifier)
       @options[:namespace_identifier] = identifier
     end
@@ -137,31 +295,11 @@ module Savon
       @options[:namespaces] = namespaces
     end
 
-    # Proxy server to use for all requests.
-    def proxy(proxy)
-      @options[:proxy] = proxy unless proxy.nil?
-    end
-
-    # A Hash of HTTP headers.
+    # A Hash of HTTP headers sent with every request.
     def headers(headers)
       @options[:headers] = headers
     end
 
-    # Open timeout in seconds.
-    def open_timeout(open_timeout)
-      @options[:open_timeout] = open_timeout
-    end
-
-    # Read timeout in seconds.
-    def read_timeout(read_timeout)
-      @options[:read_timeout] = read_timeout
-    end
-
-    # Write timeout in seconds.
-    def write_timeout(write_timeout)
-      @options[:write_timeout] = write_timeout
-    end
-
     # The encoding to use. Defaults to "UTF-8".
     def encoding(encoding)
       @options[:encoding] = encoding
@@ -210,7 +348,7 @@ module Savon
 
     # Changes the Logger's log level.
     def log_level(level)
-      levels = { :debug => 0, :info => 1, :warn => 2, :error => 3, :fatal => 4 }
+      levels = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }
 
       unless levels.include? level
         raise ArgumentError, "Invalid log level: #{level.inspect}\n" \
@@ -220,7 +358,7 @@ module Savon
       @options[:logger].level = levels[level]
     end
 
-    # To log headers or not.
+    # Whether to log headers.
     def log_headers(log_headers)
       @options[:log_headers] = log_headers
     end
@@ -235,90 +373,6 @@ module Savon
       @options[:pretty_print_xml] = pretty_print_xml
     end
 
-    # Specifies the SSL version to use.
-    def ssl_version(version)
-      @options[:ssl_version] = version
-    end
-
-    # Specifies the SSL version to use.
-    def ssl_min_version(version)
-      @options[:ssl_min_version] = version
-    end
-
-    # Specifies the SSL version to use.
-    def ssl_max_version(version)
-      @options[:ssl_max_version] = version
-    end
-
-    # Whether and how to to verify the connection.
-    def ssl_verify_mode(verify_mode)
-      @options[:ssl_verify_mode] = verify_mode
-    end
-
-    # Sets the cert key file to use.
-    def ssl_cert_key_file(file)
-      @options[:ssl_cert_key_file] = file
-    end
-
-    # Sets the cert key to use.
-    def ssl_cert_key(key)
-      @options[:ssl_cert_key] = key
-    end
-
-    # Sets the cert key password to use.
-    def ssl_cert_key_password(password)
-      @options[:ssl_cert_key_password] = password
-    end
-
-    # Sets the cert file to use.
-    def ssl_cert_file(file)
-      @options[:ssl_cert_file] = file
-    end
-
-    # Sets the cert to use.
-    def ssl_cert(cert)
-      @options[:ssl_cert] = cert
-    end
-
-    # Sets the ca cert file to use.
-    def ssl_ca_cert_file(file)
-      @options[:ssl_ca_cert_file] = file
-    end
-
-    # Sets the ca cert to use.
-    def ssl_ca_cert(cert)
-      @options[:ssl_ca_cert] = cert
-    end
-
-    def ssl_ciphers(ciphers)
-      @options[:ssl_ciphers] = ciphers
-    end
-
-    # Sets the ca cert path.
-    def ssl_ca_cert_path(path)
-      @options[:ssl_ca_cert_path] = path
-    end
-
-    # Sets the ssl cert store.
-    def ssl_cert_store(store)
-      @options[:ssl_cert_store] = store
-    end
-
-    # HTTP basic auth credentials.
-    def basic_auth(*credentials)
-      @options[:basic_auth] = credentials.flatten
-    end
-
-    # HTTP digest auth credentials.
-    def digest_auth(*credentials)
-      @options[:digest_auth] = credentials.flatten
-    end
-
-    # NTLM auth credentials.
-    def ntlm(*credentials)
-      @options[:ntlm] = credentials.flatten
-    end
-
     # Instruct Nori whether to strip namespaces from XML nodes.
     def strip_namespaces(strip_namespaces)
       @options[:strip_namespaces] = strip_namespaces
@@ -329,57 +383,113 @@ module Savon
       @options[:delete_namespace_attributes] = delete_namespace_attributes
     end
 
+    # The value Nori assigns to empty XML tags in the SOAP response.
+    # Defaults to nil, matching Nori's default; set to "" to map empty tags
+    # to an empty String instead.
+    def empty_tag_value(value)
+      @options[:empty_tag_value] = value
+    end
+
+    # Instruct Nori whether to convert dashes in response tag names to
+    # underscores before they become Hash keys. Defaults to true.
+    def convert_dashes_to_underscores(convert)
+      @options[:convert_dashes_to_underscores] = convert
+    end
+
+    # Instruct Nori whether to scrub invalid byte sequences from the response
+    # body before parsing it. Defaults to true, which lets responses containing
+    # invalid characters still be parsed.
+    def scrub_xml(scrub)
+      @options[:scrub_xml] = scrub
+    end
+
     # Tell Gyoku how to convert Hash key Symbols to XML tags.
     # Accepts one of :lower_camelcase, :camelcase, :upcase, or :none.
     def convert_request_keys_to(converter)
       @options[:convert_request_keys_to] = converter
     end
 
-    # Tell Gyoku to unwrap Array of Hashes
-    # Accepts a boolean, default to false
+    # Tell Gyoku to unwrap Array of Hashes.
+    # Accepts a boolean, defaults to false.
     def unwrap(unwrap)
       @options[:unwrap] = unwrap
     end
 
     # Tell Nori how to convert XML tags from the SOAP response into Hash keys.
     # Accepts a lambda or a block which receives an XML tag and returns a Hash key.
-    # Defaults to convert tags to snakecase Symbols.
+    # Defaults to converting tags to snakecase Symbols.
     def convert_response_tags_to(converter = nil, &block)
       @options[:convert_response_tags_to] = block || converter
     end
 
     # Tell Nori how to convert XML attributes on tags from the SOAP response into Hash keys.
     # Accepts a lambda or a block which receives an XML tag and returns a Hash key.
-    # Defaults to doing nothing
+    # Defaults to doing nothing.
     def convert_attributes_to(converter = nil, &block)
       @options[:convert_attributes_to] = block || converter
     end
 
     # Instruct Savon to create a multipart response if available.
     def multipart(multipart)
+      if multipart
+        warn "The global :multipart option has been a no-op since v2.13.0. " \
+          "Savon detects whether the response is multipart by checking if the " \
+          "response Content-Type header contains 'multipart'. You can remove" \
+          "this option from your code to make this warning disappear.", uplevel: 1
+      end
       @options[:multipart] = multipart
     end
 
-    # Instruct Savon what HTTPI adapter it should use instead of default
-    def adapter(adapter)
-      @options[:adapter] = adapter
-    end
-
     # Enable inclusion of WS-Addressing headers.
     def use_wsa_headers(use)
       @options[:use_wsa_headers] = use
     end
 
+    # Suppress the message tag wrapper around the SOAP body.
     def no_message_tag(bool)
       @options[:no_message_tag] = bool
     end
 
-    # Instruct requests to follow HTTP redirects.
-    def follow_redirects(follow_redirects)
-      @options[:follow_redirects] = follow_redirects
+    # HTTP transport to use. Accepts :httpi (default) or :faraday.
+    # With :faraday, set proxy, timeout, TLS, auth, redirect, and adapter
+    # details on `client.faraday`; the HTTPI transport options are not copied.
+    def transport(transport)
+      @options[:transport] = transport
+    end
+
+    private
+
+    # The default value for every global option.
+    def defaults
+      HTTPITransportOptions::TRANSPORT_DEFAULTS.merge(
+        encoding: "UTF-8",
+        soap_version: 1,
+        namespaces: {},
+        logger: Logger.new($stdout),
+        log: false,
+        log_headers: true,
+        filters: [],
+        pretty_print_xml: false,
+        raise_errors: true,
+        strip_namespaces: true,
+        delete_namespace_attributes: false,
+        empty_tag_value: nil,
+        convert_dashes_to_underscores: true,
+        scrub_xml: true,
+        convert_response_tags_to: ->(tag) { StringUtils.snakecase(tag).to_sym },
+        convert_attributes_to: ->(k, v) { [k, v] },
+        multipart: false,
+        use_wsa_headers: false,
+        no_message_tag: false,
+        unwrap: false,
+        host: nil,
+        transport: :httpi
+      )
     end
   end
 
+  # Per-request options passed to client.call.
+  # Overrides or extends the matching GlobalOptions for a single SOAP operation.
   class LocalOptions < Options
     include SharedOptions
 
@@ -387,9 +497,9 @@ module Savon
       @option_type = :local
 
       defaults = {
-        :advanced_typecasting => true,
-        :response_parser      => :nokogiri,
-        :multipart            => false
+        advanced_typecasting: true,
+        response_parser: :nokogiri,
+        multipart: false
       }
 
       super defaults.merge(options)
@@ -397,7 +507,7 @@ module Savon
 
     # The local SOAP header. Expected to be a Hash or respond to #to_s.
     # Will be merged with the global SOAP header if both are Hashes.
-    # Otherwise the local option will be prefered.
+    # Otherwise the local option will be preferred.
     def soap_header(header)
       @options[:soap_header] = header
     end
@@ -479,9 +589,16 @@ module Savon
 
     # Instruct Savon to create a multipart response if available.
     def multipart(multipart)
+      if multipart
+        warn "The local :multipart option has been a no-op since v2.13.0. " \
+            "Savon detects whether the response is multipart by checking if the " \
+            "response Content-Type header contains 'multipart'. You can remove" \
+            "this option from your code to make this warning disappear.", uplevel: 1
+      end
       @options[:multipart] = multipart
     end
 
+    # Per-request HTTP headers. Merged with global headers for each request.
     def headers(headers)
       @options[:headers] = headers
     end

data/lib/savon/qualified_message.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "gyoku"
 
 module Savon
@@ -37,7 +38,7 @@ module Savon
     private
 
     def translate_tag(key)
-      Gyoku.xml_tag(key, :key_converter => @key_converter).to_s
+      Gyoku.xml_tag(key, key_converter: @key_converter).to_s
     end
 
     def add_namespaces_to_values(values, path)