savon 2.16.0 → 2.17.4

data/lib/savon/client.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
+
 require "savon/operation"
-require "savon/request"
+require "savon/transport/httpi"
+require "savon/transport/faraday"
 require "savon/options"
 require "savon/block_interface"
 require "wasabi"
 
 module Savon
+  # The main entry point for Savon.
+  #
+  # Holds global configuration, owns the WSDL document, and dispatches
+  # named operations. A single Client instance is typically shared across
+  # multiple calls to the same service.
   class Client
-
     def initialize(globals = {}, &block)
-      unless globals.kind_of? Hash
+      unless globals.is_a? Hash
         raise_version1_initialize_error! globals
       end
 
       set_globals(globals, block)
+      @globals.validate_transport!
 
       unless wsdl_or_endpoint_and_namespace_specified?
         raise_initialization_error!
@@ -24,13 +31,25 @@ module Savon
 
     attr_reader :globals, :wsdl
 
+    # Returns the memoized Faraday::Connection for this client.
+    # Callers use this to configure middleware, SSL, auth, timeouts, and any
+    # other transport-level concern before making calls.
+    # Raises ArgumentError if transport is not :faraday.
+    def faraday
+      unless @globals[:transport] == :faraday
+        raise ArgumentError, "client.faraday is only available when transport: :faraday is set"
+      end
+
+      @faraday ||= ::Faraday.new
+    end
+
     def operations
       raise_missing_wsdl_error! unless @wsdl.document?
       @wsdl.soap_actions
     end
 
     def operation(operation_name)
-      Operation.create(operation_name, @wsdl, @globals)
+      Operation.create(operation_name, @wsdl, @globals, build_transport)
     end
 
     def call(operation_name, locals = {}, &block)
@@ -48,6 +67,15 @@ module Savon
 
     private
 
+    # Builds the transport for a single operation.
+    def build_transport
+      if @globals[:transport] == :faraday
+        Transport::Faraday.new(faraday, @globals)
+      else
+        Transport::HTTPI.new(@globals)
+      end
+    end
+
     def set_globals(globals, block)
       globals = GlobalOptions.new(globals)
       BlockInterface.new(globals).evaluate(block) if block
@@ -58,12 +86,16 @@ module Savon
     def build_wsdl_document
       @wsdl = Wasabi::Document.new
 
-      @wsdl.document    = @globals[:wsdl]        if @globals.include? :wsdl
-      @wsdl.endpoint    = @globals[:endpoint]    if @globals.include? :endpoint
-      @wsdl.namespace   = @globals[:namespace]   if @globals.include? :namespace
-      @wsdl.adapter     = @globals[:adapter]     if @globals.include? :adapter
+      @wsdl.document  = @globals[:wsdl]      if @globals.include? :wsdl
+      @wsdl.endpoint  = @globals[:endpoint]  if @globals.include? :endpoint
+      @wsdl.namespace = @globals[:namespace] if @globals.include? :namespace
 
-      @wsdl.request = WSDLRequest.new(@globals).build
+      if @globals[:transport] == :faraday
+        @wsdl.request = faraday
+      else
+        @wsdl.adapter = @globals[:adapter] if @globals.include? :adapter
+        @wsdl.request = Transport::HTTPI.new(@globals).wsdl_request
+      end
     end
 
     def wsdl_or_endpoint_and_namespace_specified?
@@ -72,9 +104,9 @@ module Savon
 
     def raise_version1_initialize_error!(object)
       raise InitializationError,
-        "Some code tries to initialize Savon with the #{object.inspect} (#{object.class}) \n" \
-        "Savon 2 expects a Hash of options for creating a new client and executing requests.\n" \
-        "Please read the updated documentation for version 2: http://savonrb.com/version2.html"
+            "Some code tries to initialize Savon with the #{object.inspect} (#{object.class}) \n" \
+            "Savon 2 expects a Hash of options for creating a new client and executing requests.\n" \
+            "Please read the updated documentation for version 2: http://savonrb.com/version2.html"
     end
 
     def raise_initialization_error!
@@ -88,6 +120,5 @@ module Savon
     def raise_missing_wsdl_error!
       raise "Unable to inspect the service without a WSDL document."
     end
-
   end
 end

data/lib/savon/effective_options.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "gyoku"
+require "uri"
+
+module Savon
+  # Resolves the effective value of options whose answer combines more than
+  # one source: the per-request options, the client options, the WSDL
+  # document, and built-in defaults.
+  #
+  # {Savon::GlobalOptions} and {Savon::LocalOptions} store what the caller
+  # said. EffectiveOptions answers what the request uses. It owns the
+  # precedence rules and exposes one reader per resolvable option, so every
+  # consumer of an option resolves it identically. Resolution is a pure read.
+  # It never mutates the options or the WSDL document.
+  class EffectiveOptions
+    # @param operation_name [Symbol] the SOAP operation being called
+    # @param wsdl [Wasabi::Document] the parsed WSDL, or an empty document
+    #   when the client was configured without one
+    # @param globals [Savon::GlobalOptions] the client-level options
+    # @param locals [Savon::LocalOptions] the per-request options
+    def initialize(operation_name, wsdl, globals, locals)
+      @operation_name = operation_name
+      @wsdl           = wsdl
+      @globals        = globals
+      @locals         = locals
+    end
+
+    # Resolves the SOAPAction of the request (SOAP 1.1 §6.1.1).
+    #
+    # An explicit local +:soap_action+ wins. A local +false+ or +nil+ disables
+    # the action, so no SOAPAction HTTP header is sent and an enabled
+    # +wsa:Action+ header stays empty. Without a local value the WSDL provides
+    # the soapAction of the operation. Without a WSDL document the operation
+    # name is converted to an XML tag as a best-effort default.
+    #
+    # @return [String, nil] the action, or +nil+ when explicitly disabled
+    def soap_action
+      return if @locals.include?(:soap_action) && !@locals[:soap_action]
+
+      @locals[:soap_action] ||
+        (@wsdl.document? && @wsdl.soap_action(@operation_name.to_sym)) ||
+        Gyoku.xml_tag(@operation_name, key_converter: @globals[:convert_request_keys_to])
+    end
+
+    # Resolves the endpoint URL the request is sent to.
+    #
+    # A global +:endpoint+ wins over the service address of the WSDL. The
+    # global +:host+ option replaces host and port of the WSDL address and
+    # keeps scheme, path and query. The override is applied to a copy. The
+    # WSDL document keeps its parsed address.
+    #
+    # @return [URI, String, nil] the endpoint as provided by the winning source
+    def endpoint
+      return @globals[:endpoint] if @globals[:endpoint]
+      return @wsdl.endpoint unless @globals[:host]
+
+      host_url = URI.parse(@globals[:host])
+      url      = @wsdl.endpoint.dup
+      url.host = host_url.host
+      url.port = host_url.port
+      url
+    end
+
+    # Resolves the WSSE auth credentials passed to Akami. A local value takes
+    # precedence over the global one. A local +false+ disables auth even when a
+    # global value is set. A local +nil+ leaves the option unset and falls
+    # through to the global value.
+    #
+    # @return [Array<String>, false, nil] the credentials, +false+ to disable,
+    #   or +nil+ when unset in both scopes
+    def wsse_auth
+      prefer_local(:wsse_auth)
+    end
+
+    # Resolves whether Akami emits a +wsu:Timestamp+ header, using the same
+    # local-over-global rule as {#wsse_auth}. A local +false+ disables it and a
+    # local +nil+ keeps the global value.
+    #
+    # @return [Boolean, nil]
+    def wsse_timestamp
+      prefer_local(:wsse_timestamp)
+    end
+
+    # Resolves the WSSE signature used to sign the request. This option is a
+    # signature object or +nil+ and has no "disable" value, so any falsy local
+    # value falls back to the global one. {Savon::Builder} and {Savon::Header}
+    # both read it and must resolve it identically.
+    #
+    # @return [Akami::WSSE::Signature, nil]
+    def wsse_signature
+      @locals[:wsse_signature] || @globals[:wsse_signature]
+    end
+
+    # Resolves the SOAP header content. When both scopes provide a Hash the two
+    # are merged and local keys win. Otherwise the local value is preferred and
+    # falls back to the global one. A Hash is rendered to XML by Gyoku. A String,
+    # or any object responding to +#to_s+, is used verbatim.
+    #
+    # @return [Hash, String, nil]
+    def soap_header
+      global = @globals[:soap_header]
+      local  = @locals[:soap_header]
+
+      if global.is_a?(Hash) && local.is_a?(Hash)
+        global.merge(local)
+      else
+        local || global
+      end
+    end
+
+    private
+
+    # Resolves an option where a local +false+ is meaningful and disables it.
+    # Only a local +nil+ falls through to the global value. Contrast with
+    # {#wsse_signature}, which treats any falsy local as unset.
+    #
+    # @param key [Symbol] the option name
+    # @return [Object, nil] the local value unless it is +nil+, else the global
+    def prefer_local(key)
+      @locals[key].nil? ? @globals[key] : @locals[key]
+    end
+  end
+end

data/lib/savon/faraday_migration_hint.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Savon
+  # Formats the replacement Faraday setup for one HTTPI-only option.
+  class FaradayMigrationHint
+    VALUE_AWARE_OPTIONS = %i[
+      proxy
+      open_timeout
+      read_timeout
+      write_timeout
+      ssl_version
+      ssl_min_version
+      ssl_max_version
+      ssl_verify_mode
+      ssl_cert_key_file
+      ssl_cert_file
+      ssl_ca_cert_file
+      ssl_ciphers
+      ssl_ca_cert_path
+      adapter
+    ].freeze
+
+    STATIC_HINTS = {
+      ssl_cert_key: "client.faraday.ssl.client_key = key",
+      ssl_cert_key_password: [
+        "key = OpenSSL::PKey.read(File.read(key_path), password)",
+        "client.faraday.ssl.client_key = key"
+      ],
+      ssl_cert: "client.faraday.ssl.client_cert = cert",
+      ssl_ca_cert: [
+        "store = OpenSSL::X509::Store.new",
+        "store.set_default_paths",
+        "store.add_cert(cert)",
+        "client.faraday.ssl.cert_store = store"
+      ],
+      ssl_cert_store: "client.faraday.ssl.cert_store = store",
+      basic_auth: "client.faraday.request :authorization, :basic, user, pass",
+      digest_auth: [
+        "gem 'faraday-digestauth'",
+        "require 'faraday/digestauth'",
+        "client.faraday.request :digest, user, pass"
+      ],
+      ntlm: [
+        "gem 'faraday-ntlm_auth'",
+        "require 'faraday/ntlm_auth'",
+        "client.faraday.adapter :net_http_persistent",
+        "client.faraday.request :ntlm_auth, auth: [user, pass, domain]"
+      ],
+      follow_redirects: [
+        "gem 'faraday-follow_redirects'",
+        "require 'faraday/follow_redirects'",
+        "client.faraday.response :follow_redirects"
+      ]
+    }.freeze
+
+    OPTIONS = (VALUE_AWARE_OPTIONS + STATIC_HINTS.keys).freeze
+
+    def initialize(option, value)
+      @option = option
+      @value = value
+    end
+
+    def message
+      hint = hint_lines
+      return "  #{option} - Use: #{hint}" unless hint.is_a?(Array)
+
+      "  #{option} - Use:\n#{hint.map { |line| "    #{line}" }.join("\n")}"
+    end
+
+    private
+
+    attr_reader :option, :value
+
+    def hint_lines
+      case option
+      when :proxy
+        "client.faraday.proxy = #{redacted_proxy_value}"
+      when :open_timeout, :read_timeout, :write_timeout
+        "client.faraday.options.#{option} = #{value.inspect}"
+      when :ssl_version, :ssl_min_version, :ssl_max_version
+        ssl_version_hint
+      when :ssl_verify_mode
+        ssl_verify_mode_hint
+      when :ssl_cert_key_file
+        ssl_cert_key_file_hint
+      when :ssl_cert_file
+        ssl_cert_file_hint
+      when :ssl_ca_cert_file
+        "client.faraday.ssl.ca_file = #{value.inspect}"
+      when :ssl_ciphers
+        "client.faraday.ssl.ciphers = #{value.inspect}"
+      when :ssl_ca_cert_path
+        "client.faraday.ssl.ca_path = #{value.inspect}"
+      when :adapter
+        adapter_hint
+      else
+        STATIC_HINTS.fetch(option)
+      end
+    end
+
+    def redacted_proxy_value
+      uri = URI.parse(value.to_s)
+      return value.inspect unless uri.absolute? && uri.host
+
+      redacted = uri.dup
+      redacted.userinfo = "..." if redacted.userinfo
+      redacted.path = "" if redacted.respond_to?(:path=)
+      redacted.query = nil if redacted.respond_to?(:query=)
+      redacted.fragment = nil if redacted.respond_to?(:fragment=)
+      redacted.to_s.inspect
+    rescue URI::InvalidURIError
+      '"[redacted proxy URL]"'
+    end
+
+    def ssl_version_hint
+      faraday_option = {
+        ssl_version: "version",
+        ssl_min_version: "min_version",
+        ssl_max_version: "max_version"
+      }.fetch(option)
+
+      "client.faraday.ssl.#{faraday_option} = #{value.inspect}"
+    end
+
+    def ssl_cert_key_file_hint
+      [
+        "key = OpenSSL::PKey.read(File.read(#{value.inspect}))",
+        "client.faraday.ssl.client_key = key"
+      ]
+    end
+
+    def ssl_cert_file_hint
+      [
+        "cert = OpenSSL::X509::Certificate.new(File.read(#{value.inspect}))",
+        "client.faraday.ssl.client_cert = cert"
+      ]
+    end
+
+    def adapter_hint
+      case value
+      when :net_http
+        "client.faraday.adapter :net_http"
+      when :httpclient
+        [
+          "gem 'faraday-httpclient'",
+          "require 'faraday/httpclient'",
+          "client.faraday.adapter :httpclient"
+        ]
+      when :excon
+        [
+          "gem 'faraday-excon'",
+          "require 'faraday/excon'",
+          "client.faraday.adapter :excon"
+        ]
+      when :net_http_persistent
+        [
+          "gem 'faraday-net_http_persistent'",
+          "require 'faraday/net_http_persistent'",
+          "client.faraday.adapter :net_http_persistent"
+        ]
+      else
+        [
+          "choose and install a Faraday adapter matching #{value.inspect}",
+          "client.faraday.adapter :net_http"
+        ]
+      end
+    end
+
+    def ssl_verify_mode_hint
+      case value
+      when :none
+        "client.faraday.ssl.verify_mode = OpenSSL::SSL::VERIFY_NONE"
+      when :peer
+        "client.faraday.ssl.verify_mode = OpenSSL::SSL::VERIFY_PEER"
+      when :fail_if_no_peer_cert
+        "client.faraday.ssl.verify_mode = OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT"
+      when :client_once
+        "client.faraday.ssl.verify_mode = OpenSSL::SSL::VERIFY_CLIENT_ONCE"
+      else
+        "client.faraday.ssl.verify_mode = OpenSSL::SSL::VERIFY_PEER or OpenSSL::SSL::VERIFY_NONE"
+      end
+    end
+  end
+end

data/lib/savon/header.rb

@@ -1,89 +1,136 @@
 # frozen_string_literal: true
+
 require "akami"
 require "gyoku"
-require "securerandom"
+require "savon/addressing"
 
 module Savon
+  # Assembles the SOAP +Header+ element of a request envelope and renders it to
+  # XML.
+  #
+  # A SOAP Header carries a request's out-of-band metadata. This object is
+  # responsible for every header block Savon can emit, concatenated in this
+  # order:
+  #
+  # 1. application headers supplied by the caller (the +soap_header+ option),
+  # 2. the WS-Addressing headers, rendered by {Savon::Addressing},
+  # 3. the WS-Security header with UsernameToken credentials, a +wsu:Timestamp+
+  #    and an XML Signature (OASIS WSS SOAP Message Security 1.1).
+  #
+  # WS-Security markup is delegated to Akami and Hash-to-XML conversion to Gyoku.
   class Header
+    # @param globals [Savon::GlobalOptions] client-level options, read for the
+    #   Gyoku key converter (+:convert_request_keys_to+) and the WS-Addressing
+    #   toggle (+:use_wsa_headers+)
+    # @param effective [Savon::EffectiveOptions] resolves the WSSE, soap_header,
+    #   soap_action and endpoint values for the request
+    def initialize(globals, effective)
+      @gyoku_options  = { key_converter: globals[:convert_request_keys_to] }
+
+      @wsse_auth      = effective.wsse_auth
+      @wsse_timestamp = effective.wsse_timestamp
+      @wsse_signature = effective.wsse_signature
+      @soap_header    = effective.soap_header
+
+      @addressing = build_addressing(globals, effective)
+      @header     = build
+    end
 
-    def initialize(globals, locals)
-      @gyoku_options  = { :key_converter => globals[:convert_request_keys_to] }
-
-      @wsse_auth      = locals[:wsse_auth].nil? ? globals[:wsse_auth] : locals[:wsse_auth]
-      @wsse_timestamp = locals[:wsse_timestamp].nil? ? globals[:wsse_timestamp] : locals[:wsse_timestamp]
-      @wsse_signature = locals[:wsse_signature].nil? ? globals[:wsse_signature] : locals[:wsse_signature]
-
-      @global_header  = globals[:soap_header]
-      @local_header   = locals[:soap_header]
-
-      @globals        = globals
-      @locals         = locals
+    attr_reader :gyoku_options, :wsse_auth, :wsse_timestamp, :wsse_signature
 
-      @header = build
+    # Returns the XML attributes of the enclosing Header element. Only the
+    # WS-Addressing section declares one, the +xmlns:wsa+ prefix.
+    #
+    # @return [Hash{String => String}]
+    def attributes
+      @addressing.namespace_attributes
     end
 
-    attr_reader :local_header, :global_header, :gyoku_options,
-                :wsse_auth, :wsse_timestamp, :wsse_signature
-
+    # @return [Boolean] whether the rendered header is empty, i.e. there is no
+    #   header content to include in the envelope
     def empty?
       @header.empty?
     end
 
+    # Returns the rendered SOAP header XML. The header is built once during
+    # construction and cached, so this is a cheap, repeatable read.
+    #
+    # @return [String] the header XML (may be empty)
     def to_s
       @header
     end
 
     private
 
+    # Constructs the WS-Addressing section from the resolved request values.
+    # Resolving the endpoint raises without a WSDL document and without a
+    # global +:endpoint+, so action and endpoint are only resolved when the
+    # +:use_wsa_headers+ global asks for the headers.
+    #
+    # @return [Savon::Addressing]
+    def build_addressing(globals, effective)
+      return Addressing.new(enabled: false) unless globals[:use_wsa_headers]
+
+      Addressing.new(
+        enabled: true,
+        action: effective.soap_action,
+        to: effective.endpoint
+      )
+    end
+
+    # Concatenates the three header sections in document order: caller content,
+    # WS-Addressing, then WSSE security.
+    #
+    # @return [String]
     def build
-      build_header + build_wsa_header + build_wsse_header
+      build_header + @addressing.to_xml + build_wsse_header
     end
 
+    # Renders the resolved soap_header. {Savon::EffectiveOptions#soap_header}
+    # merges the global and local values, so there is nothing to combine here.
+    # Hash-to-XML conversion only. Strings pass through.
+    #
+    # @return [String]
     def build_header
-      header =
-        if global_header.kind_of?(Hash) && local_header.kind_of?(Hash)
-          global_header.merge(local_header)
-        elsif local_header
-          local_header
-        else
-          global_header
-        end
-
-      convert_to_xml(header)
+      convert_to_xml(@soap_header)
     end
 
+    # Builds the WS-Security header via Akami, or an empty string when no WSSE
+    # content (credentials, timestamp or signature) applies.
+    #
+    # @return [String]
     def build_wsse_header
       wsse_header = akami
       wsse_header.respond_to?(:to_xml) ? wsse_header.to_xml : ""
     end
 
-    def build_wsa_header
-       return '' unless @globals[:use_wsa_headers]
-       convert_to_xml({
-         'wsa:Action' => @locals[:soap_action],
-         'wsa:To' => @globals[:endpoint],
-         'wsa:MessageID' => "urn:uuid:#{SecureRandom.uuid}"
-       })
-    end
-
+    # Renders a header value to XML. A Hash goes through Gyoku (honouring the
+    # configured key converter), anything else is coerced with +#to_s+.
+    #
+    # @param hash_or_string [Hash, #to_s] the header content
+    # @return [String]
     def convert_to_xml(hash_or_string)
-      if hash_or_string.kind_of? Hash
+      if hash_or_string.is_a? Hash
         Gyoku.xml(hash_or_string, gyoku_options)
       else
         hash_or_string.to_s
       end
     end
 
+    # Configures an Akami WSSE object from the resolved WSSE options. Sets the
+    # UsernameToken credentials, enables the wsu:Timestamp, and attaches the XML
+    # Signature when a document has been assigned to it.
+    #
+    # @return [Akami::WSSE] configured, not yet serialized
     def akami
       wsse = Akami.wsse
       wsse.credentials(*wsse_auth) if wsse_auth
       wsse.timestamp = wsse_timestamp if wsse_timestamp
-      if wsse_signature && wsse_signature.have_document?
+      if wsse_signature&.have_document?
         wsse.signature = wsse_signature
       end
 
       wsse
     end
-
   end
 end

data/lib/savon/http_error.rb

@@ -2,26 +2,26 @@
 
 module Savon
   class HTTPError < Error
-
     def self.present?(http)
       http.error?
     end
 
-    def initialize(http)
-      @http = http
+    def initialize(transport_response)
+      @transport_response = transport_response
     end
 
-    attr_reader :http
+    def http
+      @transport_response
+    end
 
     def to_s
-      String.new("HTTP error (#{@http.code})").tap do |str_error|
-        str_error << ": #{@http.body}" unless @http.body.empty?
+      String.new("HTTP error (#{http.code})").tap do |str_error|
+        str_error << ": #{http.body}" unless http.body.empty?
       end
     end
 
     def to_hash
-      { :code => @http.code, :headers => @http.headers, :body => @http.body }
+      { code: http.code, headers: http.headers, body: http.body }
     end
-
   end
 end

data/lib/savon/log_message.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
+
 require "nokogiri"
 
 module Savon
   class LogMessage
-
     def initialize(message, filters = [], pretty_print = false)
       @message      = message
       @filters      = filters
@@ -46,8 +46,7 @@ module Savon
     end
 
     def nokogiri_options
-      @pretty_print ? { :indent => 2 } : { :save_with => Nokogiri::XML::Node::SaveOptions::AS_XML }
+      @pretty_print ? { indent: 2 } : { save_with: Nokogiri::XML::Node::SaveOptions::AS_XML }
     end
-
   end
 end

data/lib/savon/message.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
+
 require "savon/qualified_message"
 require "gyoku"
 
 module Savon
   class Message
-
     def initialize(message_tag, namespace_identifier, types, used_namespaces, message, element_form_default, key_converter, unwrap)
       @message_tag = message_tag
       @namespace_identifier = namespace_identifier
@@ -18,21 +18,20 @@ module Savon
     end
 
     def to_s
-      return @message.to_s unless @message.kind_of? Hash
+      return @message.to_s unless @message.is_a? Hash
 
       if @element_form_default == :qualified
         @message = QualifiedMessage.new(@types, @used_namespaces, @key_converter).to_hash(@message, [@message_tag.to_s])
       end
 
       gyoku_options = {
-        :element_form_default => @element_form_default,
-        :namespace            => @namespace_identifier,
-        :key_converter        => @key_converter,
-        :unwrap               => @unwrap
+        element_form_default: @element_form_default,
+        namespace: @namespace_identifier,
+        key_converter: @key_converter,
+        unwrap: @unwrap
       }
 
       Gyoku.xml(@message, gyoku_options)
     end
-
   end
 end