savon 2.16.0 → 2.17.0

data/lib/savon/options.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
+
 require "logger"
 require "httpi"
 
 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 +21,7 @@ module Savon
 
     def []=(option, value)
       value = [value].flatten
-      self.send(option, *value)
+      send(option, *value)
     end
 
     def include?(option)
@@ -29,7 +32,7 @@ module Savon
 
     def assign(options)
       options.each do |option, value|
-        self.send(option, value)
+        send(option, value)
       end
     end
 
@@ -38,6 +41,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 +51,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,33 +73,229 @@ module Savon
     end
   end
 
+  # HTTPI-specific transport options included in GlobalOptions.
+  #
+  # Every option in this module is handled by HTTPI and has no effect when
+  # transport: :faraday is set. Faraday callers configure these concerns
+  # directly on the Faraday::Connection returned by client.faraday.
+  module HTTPITransportOptions
+    # Maps each httpi-only option to the Faraday equivalent so the
+    # error raised at init tells the caller exactly what to do instead.
+    # Options with a :default entry are only flagged when the caller
+    # sets a value that differs from the GlobalOptions default.
+    FARADAY_INCOMPATIBLE_GLOBALS = {
+      proxy: { hint: "client.faraday.proxy = url" },
+      open_timeout: { hint: "client.faraday.options.timeout = N" },
+      read_timeout: { hint: "client.faraday.options.timeout = N" },
+      write_timeout: { hint: "client.faraday.options.write_timeout = N" },
+      ssl_version: { hint: "client.faraday.ssl.version = version" },
+      ssl_min_version: { hint: "client.faraday.ssl.min_version = version" },
+      ssl_max_version: { hint: "client.faraday.ssl.max_version = version" },
+      ssl_verify_mode: { hint: "client.faraday.ssl.verify = true/false" },
+      ssl_cert_key_file: { hint: "client.faraday.ssl.client_key_file = path" },
+      ssl_cert_key: { hint: "client.faraday.ssl.client_key = key" },
+      ssl_cert_key_password: { hint: "configure ssl context on client.faraday.ssl" },
+      ssl_cert_file: { hint: "client.faraday.ssl.client_cert_file = path" },
+      ssl_cert: { hint: "client.faraday.ssl.client_cert = cert" },
+      ssl_ca_cert_file: { hint: "client.faraday.ssl.ca_file = path" },
+      ssl_ca_cert: { hint: "client.faraday.ssl.ca_cert = cert" },
+      ssl_ciphers: { hint: "client.faraday.ssl.ciphers = ciphers" },
+      ssl_ca_cert_path: { hint: "client.faraday.ssl.ca_path = path" },
+      ssl_cert_store: { hint: "client.faraday.ssl.cert_store = store" },
+      basic_auth: { hint: "client.faraday.request :basic_auth, user, pass" },
+      digest_auth: { hint: "client.faraday.request :authorization, :Digest, credentials" },
+      ntlm: { hint: "client.faraday.request :ntlm, user, pass" },
+      follow_redirects: { hint: "client.faraday.use :follow_redirects", default: false },
+      adapter: { hint: "client.faraday.adapter :net_http", default: nil }
+    }.freeze
+
+    # Validates that the chosen transport is compatible with the options set.
+    # Must be called after all options (including any block-form options) are set.
+    # Collects every conflict and raises a single InitializationError listing all
+    # problems and solutions at once.
+    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, config|
+        next unless include?(option)
+        next if config.key?(:default) && self[option] == config[:default]
+
+        "  #{option} - Use: #{config[:hint]}"
+      }
+
+      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
+
+    # 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
+        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: ->(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,
+
+        # httpi transport defaults
+        adapter: nil,
+        follow_redirects: false
       }
 
       options = defaults.merge(options)
@@ -112,7 +314,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 +329,7 @@ module Savon
       @options[:namespace] = namespace
     end
 
-    # The namespace identifer.
+    # The namespace identifier.
     def namespace_identifier(identifier)
       @options[:namespace_identifier] = identifier
     end
@@ -137,31 +339,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 +392,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 +402,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 +417,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
@@ -335,22 +433,22 @@ module Savon
       @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
@@ -360,26 +458,27 @@ module Savon
       @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.
+    # When set to :faraday, configure transport concerns directly on the
+    # Faraday::Connection returned by client.faraday instead of using
+    # the HTTPITransportOptions.
+    def transport(transport)
+      @options[:transport] = transport
     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 +486,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 +496,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
@@ -482,6 +581,7 @@ module Savon
       @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)

data/lib/savon/response.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "nori"
 require "savon/soap_fault"
 require "savon/http_error"
@@ -6,14 +7,14 @@ require "savon/http_error"
 module Savon
   class Response
     CRLF = /\r\n/
-    WSP  = /[#{%Q|\x9\x20|}]/
+    WSP  = /[\t ]/
 
     def initialize(http, globals, locals)
-      @http    = http
-      @globals = globals
-      @locals  = locals
-      @attachments = []
-      @xml     = ''
+      @http            = http
+      @globals         = globals
+      @locals          = locals
+      @attachments     = []
+      @xml             = ''
       @has_parsed_body = false
 
       build_soap_and_http_errors!
@@ -25,7 +26,7 @@ module Savon
     def success?
       !soap_fault? && !http_error?
     end
-    alias_method :successful?, :success?
+    alias successful? success?
 
     def soap_fault?
       SOAPFault.present?(@http, xml)
@@ -43,15 +44,16 @@ module Savon
       find('Body')
     end
 
-    alias_method :to_hash, :body
+    alias to_hash body
 
     def to_array(*path)
-      result = path.inject body do |memo, key|
+      result = path.inject(body) { |memo, key|
         return [] if memo[key].nil?
+
         memo[key]
-      end
+      }
 
-      result.kind_of?(Array) ? result.compact : [result].compact
+      result.is_a?(Array) ? result.compact : [result].compact
     end
 
     def hash
@@ -72,8 +74,8 @@ module Savon
       end
     end
 
-    alias_method :to_xml, :xml
-    alias_method :to_s,   :xml
+    alias to_xml xml
+    alias to_s xml
 
     def doc
       @doc ||= Nokogiri.XML(xml)
@@ -107,19 +109,20 @@ module Savon
 
     def boundary
       return unless multipart?
+
       Mail::Field.new('content-type', http.headers['content-type']).parameters['boundary']
     end
 
     def parse_body
       http.body.force_encoding Encoding::ASCII_8BIT
       parts = http.body.split(/(?:\A|\r\n)--#{Regexp.escape(boundary)}(?=(?:--)?\s*$)/)
-      parts[1..-1].to_a.each_with_index do |part, index|
+      parts[1..].to_a.each_with_index do |part, index|
         header_part, body_part = part.lstrip.split(/#{CRLF}#{CRLF}|#{CRLF}#{WSP}*#{CRLF}(?!#{WSP})/m, 2)
         section = Mail::Part.new(
           body: body_part
         )
         section.header = header_part
-        if index == 0
+        if index.zero?
           @xml = section.body.to_s
         else
           @attachments << section
@@ -139,7 +142,7 @@ module Savon
     end
 
     def raise_invalid_response_error!
-      raise InvalidResponseError, "Unable to parse response body:\n" + xml.inspect
+      raise InvalidResponseError, "Unable to parse response body:\n#{xml.inspect}"
     end
 
     def xml_namespaces
@@ -150,17 +153,16 @@ module Savon
       return @nori if @nori
 
       nori_options = {
-        :delete_namespace_attributes => @globals[:delete_namespace_attributes],
-        :strip_namespaces            => @globals[:strip_namespaces],
-        :convert_tags_to             => @globals[:convert_response_tags_to],
-        :convert_attributes_to       => @globals[:convert_attributes_to],
-        :advanced_typecasting        => @locals[:advanced_typecasting],
-        :parser                      => @locals[:response_parser]
+        delete_namespace_attributes: @globals[:delete_namespace_attributes],
+        strip_namespaces: @globals[:strip_namespaces],
+        convert_tags_to: @globals[:convert_response_tags_to],
+        convert_attributes_to: @globals[:convert_attributes_to],
+        advanced_typecasting: @locals[:advanced_typecasting],
+        parser: @locals[:response_parser]
       }
 
       non_nil_nori_options = nori_options.reject { |_, value| value.nil? }
       @nori = Nori.new(non_nil_nori_options)
     end
-
   end
 end