savon 2.16.0 → 2.17.4

data/lib/savon/mock/expectation.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
+
 require "httpi"
+require "savon/transport/response"
 
 module Savon
+  # A single test expectation set up by Savon's mock interface.
+  # One expectation covers one operation call in one test.
+  #
+  # Records the expected operation name and message, captures what was
+  # actually called, and either returns a synthetic response or raises
+  # an error on mismatch.
   class MockExpectation
-
     def initialize(operation_name)
-      @expected = { :operation_name => operation_name }
+      @expected = { operation_name: operation_name }
       @actual = nil
     end
 
@@ -15,15 +22,15 @@ module Savon
     end
 
     def returns(response)
-      response = { :code => 200, :headers => {}, :body => response } if response.kind_of?(String)
+      response = { code: 200, headers: {}, body: response } if response.is_a?(String)
       @response = response
       self
     end
 
-    def actual(operation_name, builder, globals, locals)
+    def actual(operation_name, _builder, _globals, locals)
       @actual = {
-        :operation_name => operation_name,
-        :message        => locals[:message]
+        operation_name: operation_name,
+        message: locals[:message]
       }
     end
 
@@ -37,45 +44,52 @@ module Savon
       verify_message!
     end
 
+    # Builds and returns a Transport::Response from the configured response hash.
+    #
+    # @return [Transport::Response]
+    # @raise  [ExpectationError] if no response was configured for this expectation
     def response!
       unless @response
         raise ExpectationError, "This expectation was not set up with a response."
       end
 
-      HTTPI::Response.new(@response[:code], @response[:headers], @response[:body])
+      Transport::Response.new(@response[:code], @response[:headers], @response[:body])
     end
 
     private
 
     def verify_operation_name!
-      unless @expected[:operation_name] == @actual[:operation_name]
-        raise ExpectationError, "Expected a request to the #{@expected[:operation_name].inspect} operation.\n" \
-                                "Received a request to the #{@actual[:operation_name].inspect} operation instead."
-      end
+      return if @expected[:operation_name] == @actual[:operation_name]
+
+      raise ExpectationError, "Expected a request to the #{@expected[:operation_name].inspect} operation.\n" \
+                              "Received a request to the #{@actual[:operation_name].inspect} operation instead."
     end
 
     def verify_message!
       return if @expected[:message].eql? :any
-      unless equals_except_any(@expected[:message], @actual[:message])
-        expected_message = "  with this message: #{@expected[:message].inspect}" if @expected[:message]
-        expected_message ||= "  with no message."
 
-        actual_message = "  with this message: #{@actual[:message].inspect}" if @actual[:message]
-        actual_message ||= "  with no message."
+      return if equals_except_any(@expected[:message], @actual[:message])
 
-        raise ExpectationError, "Expected a request to the #{@expected[:operation_name].inspect} operation\n#{expected_message}\n" \
-        "Received a request to the #{@actual[:operation_name].inspect} operation\n#{actual_message}"
-      end
+      expected_message = "  with this message: #{@expected[:message].inspect}" if @expected[:message]
+      expected_message ||= "  with no message."
+
+      actual_message = "  with this message: #{@actual[:message].inspect}" if @actual[:message]
+      actual_message ||= "  with no message."
+
+      raise ExpectationError, "Expected a request to the #{@expected[:operation_name].inspect} operation\n#{expected_message}\n" \
+      "Received a request to the #{@actual[:operation_name].inspect} operation\n#{actual_message}"
     end
 
     def equals_except_any(msg_expected, msg_real)
-      return true if msg_expected === msg_real
-      return false if (msg_expected.nil? || msg_real.nil?) # If both are nil has returned true
+      # === allows RSpec matchers (e.g. include(:key)) to be used as expected values
+      return true if msg_expected === msg_real # rubocop:disable Style/CaseEquality
+      return false if msg_expected.nil? || msg_real.nil? # If both are nil has returned true
+
       msg_expected.each do |key, expected_value|
-        next if (expected_value == :any &&  msg_real.include?(key))
+        next if expected_value == :any && msg_real.include?(key)
         return false if expected_value != msg_real[key]
       end
-      return true
+      true
     end
   end
 end

data/lib/savon/mock/spec_helper.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
+
 require "savon/mock"
 
 module Savon
   module SpecHelper
-
     class Interface
-
       def mock!
         Savon.observers << self
       end
@@ -27,14 +26,12 @@ module Savon
       def notify(operation_name, builder, globals, locals)
         expectation = expectations.shift
 
-        if expectation
-          expectation.actual(operation_name, builder, globals, locals)
+        raise ExpectationError, "Unexpected request to the #{operation_name.inspect} operation." unless expectation
+
+        expectation.actual(operation_name, builder, globals, locals)
 
-          expectation.verify!
-          expectation.response!
-        else
-          raise ExpectationError, "Unexpected request to the #{operation_name.inspect} operation."
-        end
+        expectation.verify!
+        expectation.response!
       rescue ExpectationError
         @expectations.clear
         raise
@@ -42,12 +39,12 @@ module Savon
 
       def verify!
         return if expectations.empty?
+
         expectations.each(&:verify!)
       rescue ExpectationError
         @expectations.clear
         raise
       end
-
     end
 
     def savon
@@ -58,6 +55,5 @@ module Savon
       super if defined? super
       savon.verify!
     end
-
   end
 end

data/lib/savon/mock.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Savon
   class ExpectationError < StandardError; end
 end

data/lib/savon/model.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
+
 module Savon
   module Model
-
     def self.extended(base)
       base.setup
     end
@@ -28,26 +28,30 @@ module Savon
 
     # Defines a class-level SOAP operation.
     def define_class_operation(operation)
-      class_operation_module.module_eval %{
-        def #{StringUtils.snakecase(operation.to_s)}(locals = {})
-          client.call #{operation.inspect}, locals
-        end
-      }
+      method_name = operation_method_name(operation)
+
+      class_operation_module.define_method(method_name) do |locals = {}|
+        client.call operation, locals
+      end
     end
 
     # Defines an instance-level SOAP operation.
     def define_instance_operation(operation)
-      instance_operation_module.module_eval %{
-        def #{StringUtils.snakecase(operation.to_s)}(locals = {})
-          self.class.#{StringUtils.snakecase(operation.to_s)} locals
-        end
-      }
+      method_name = operation_method_name(operation)
+
+      instance_operation_module.define_method(method_name) do |locals = {}|
+        self.class.public_send(method_name, locals)
+      end
+    end
+
+    # Returns the generated Ruby method name for a SOAP operation.
+    def operation_method_name(operation)
+      StringUtils.snakecase(operation.to_s).to_sym
     end
 
     # Class methods.
     def class_operation_module
-      @class_operation_module ||= Module.new {
-
+      @class_operation_module ||= Module.new do
         def client(globals = {})
           @client ||= Savon::Client.new(globals)
         rescue InitializationError
@@ -60,26 +64,22 @@ module Savon
 
         def raise_initialization_error!
           raise InitializationError,
-            "Expected the model to be initialized with either a WSDL document or the SOAP endpoint and target namespace options.\n" \
-            "Make sure to setup the model by calling the .client class method before calling the .global method.\n\n" \
-            "client(wsdl: '/Users/me/project/service.wsdl')                              # to use a local WSDL document\n" \
-            "client(wsdl: 'http://example.com?wsdl')                                     # to use a remote WSDL document\n" \
-            "client(endpoint: 'http://example.com', namespace: 'http://v1.example.com')  # if you don't have a WSDL document"
+                "Expected the model to be initialized with either a WSDL document or the SOAP endpoint and target namespace options.\n" \
+                "Make sure to setup the model by calling the .client class method before calling the .global method.\n\n" \
+                "client(wsdl: '/Users/me/project/service.wsdl')                              # to use a local WSDL document\n" \
+                "client(wsdl: 'http://example.com?wsdl')                                     # to use a remote WSDL document\n" \
+                "client(endpoint: 'http://example.com', namespace: 'http://v1.example.com')  # if you don't have a WSDL document"
         end
-
-      }.tap { |mod| extend(mod) }
+      end.tap { |mod| extend(mod) }
     end
 
     # Instance methods.
     def instance_operation_module
-      @instance_operation_module ||= Module.new {
-
+      @instance_operation_module ||= Module.new do
         def client
           self.class.client
         end
-
-      }.tap { |mod| include(mod) }
+      end.tap { |mod| include(mod) }
     end
-
   end
 end

data/lib/savon/operation.rb

@@ -1,52 +1,67 @@
 # frozen_string_literal: true
+
 require "savon/options"
+require "savon/effective_options"
 require "savon/block_interface"
-require "savon/request"
 require "savon/builder"
 require "savon/response"
-require "savon/request_logger"
 require "savon/http_error"
+require "savon/transport/httpi"
+require "savon/transport/faraday"
 require "mail"
 
 module Savon
+  # Represents a single named SOAP operation.
+  #
+  # Bridges the SOAP layer (envelope building, action headers, multipart) and the
+  # transport layer (execution, logging). Knows nothing about transport internals
+  # such as proxy, SSL, or auth.
   class Operation
-
+    # SOAP Content-Type values indexed by SOAP version.
+    # SOAP 1.1 §6 (HTTP binding), SOAP 1.2 Part 2 §7.1.4 (HTTP media type)
+    CONTENT_TYPE = {
+      1 => "text/xml;charset=%s",
+      2 => "application/soap+xml;charset=%s"
+    }.freeze
+
+    # Maps SOAP version to the base MIME type used in multipart requests.
+    # RFC 2387 §3.1 (multipart/related Content-Type parameter)
     SOAP_REQUEST_TYPE = {
       1 => "text/xml",
       2 => "application/soap+xml"
-    }
+    }.freeze
 
-    def self.create(operation_name, wsdl, globals)
+    def self.create(operation_name, wsdl, globals, transport)
       if wsdl.document?
         ensure_name_is_symbol! operation_name
-        ensure_exists! operation_name, wsdl
+        ensure_exists! operation_name, wsdl, transport
       end
 
-      new(operation_name, wsdl, globals)
+      new(operation_name, wsdl, globals, transport)
     end
 
-    def self.ensure_exists!(operation_name, wsdl)
+    # Verifies the operation is provided by the WSDL.
+    def self.ensure_exists!(operation_name, wsdl, transport)
       unless wsdl.soap_actions.include? operation_name
         raise UnknownOperationError, "Unable to find SOAP operation: #{operation_name.inspect}\n" \
                                      "Operations provided by your service: #{wsdl.soap_actions.inspect}"
       end
     rescue Wasabi::Resolver::HTTPError => e
-      raise HTTPError.new(e.response)
+      raise HTTPError, transport.normalize_response(e.response)
     end
 
     def self.ensure_name_is_symbol!(operation_name)
-      unless operation_name.kind_of? Symbol
-        raise ArgumentError, "Expected the first parameter (the name of the operation to call) to be a symbol\n" \
-                             "Actual: #{operation_name.inspect} (#{operation_name.class})"
-      end
-    end
+      return if operation_name.is_a? Symbol
 
-    def initialize(name, wsdl, globals)
-      @name = name
-      @wsdl = wsdl
-      @globals = globals
+      raise ArgumentError, "Expected the first parameter (the name of the operation to call) to be a symbol\n" \
+                           "Actual: #{operation_name.inspect} (#{operation_name.class})"
+    end
 
-      @logger = RequestLogger.new(globals)
+    def initialize(name, wsdl, globals, transport)
+      @name      = name
+      @wsdl      = wsdl
+      @globals   = globals
+      @transport = transport
     end
 
     def build(locals = {}, &block)
@@ -54,28 +69,45 @@ module Savon
       Builder.new(@name, @wsdl, @globals, @locals)
     end
 
+    # Executes the SOAP operation and returns a Savon::Response.
+    #
+    # Observer short-circuit: if any registered observer returns a
+    # Transport::Response (or legacy HTTPI::Response), the HTTP call
+    # is skipped and that response is used directly.
     def call(locals = {}, &block)
       builder = build(locals, &block)
+      observer_response = Savon.notify_observers(@name, builder, @globals, @locals)
+
+      transport_response =
+        if observer_response.nil?
+          body = builder.to_s
+          headers = soap_headers(builder)
+          @transport.post(endpoint.to_s, headers, body, @locals)
+        else
+          normalize_observer_response(observer_response)
+        end
 
-      response = Savon.notify_observers(@name, builder, @globals, @locals)
-      response ||= call_with_logging build_request(builder)
-
-      raise_expected_httpi_response! unless response.kind_of?(HTTPI::Response)
-
-      create_response(response)
+      Response.new(transport_response, @globals, @locals)
     end
 
+    # Builds and returns the HTTPI::Request that would be sent for this
+    # operation, without executing it. Useful for inspection and debugging.
+    # Not supported with transport: :faraday.
     def request(locals = {}, &block)
+      if @globals[:transport] == :faraday
+        raise ArgumentError, "#request returns an HTTPI::Request and is not supported " \
+                             "with transport: :faraday. Use client.faraday to configure " \
+                             "the connection"
+      end
+
       builder = build(locals, &block)
-      build_request(builder)
+      # Build the body before soap_headers - see #call.
+      body = builder.to_s
+      @transport.to_httpi_request(endpoint.to_s, soap_headers(builder), body, @locals)
     end
 
     private
 
-    def create_response(response)
-      Response.new(response, @globals, @locals)
-    end
-
     def set_locals(locals, block)
       locals = LocalOptions.new(locals)
       BlockInterface.new(locals).evaluate(block) if block
@@ -83,65 +115,69 @@ module Savon
       @locals = locals
     end
 
-    def call_with_logging(request)
-      @logger.log(request) { HTTPI.post(request, @globals[:adapter]) }
+    # The effective options view for the current request. Built on demand
+    # instead of being cached, so it always reflects the current per-request
+    # options.
+    def effective_options
+      EffectiveOptions.new(@name, @wsdl, @globals, @locals)
     end
 
-    def build_request(builder)
-      @locals[:soap_action] ||= soap_action
-      @globals[:endpoint] ||= endpoint
-
-      request = SOAPRequest.new(@globals).build(
-        :soap_action => soap_action,
-        :cookies     => @locals[:cookies],
-        :headers     => @locals[:headers]
-      )
-
-      request.url = endpoint
-      request.body = builder.to_s
+    # Assembles the SOAP-level request headers for the given builder.
+    #
+    # Our responsibility regardless of transport:
+    #   * Content-Type (SOAP 1.1 §6 / SOAP 1.2 Part 2 §7.1.4)
+    #   * SOAPAction (SOAP 1.1 §6.1.1)
+    #   * Multipart Content-Type (RFC 2387), MIME-Version (RFC 2045 §4), Accept-Encoding (RFC 9110 §12.5.3)
+    def soap_headers(builder)
+      headers = {}
 
       if builder.multipart
-        request.gzip
-        request.headers["Content-Type"] = ["multipart/related",
-                                           "type=\"#{SOAP_REQUEST_TYPE[@globals[:soap_version]]}\"",
-                                           "start=\"#{builder.multipart[:start]}\"",
-                                           "boundary=\"#{builder.multipart[:multipart_boundary]}\""].join("; ")
-        request.headers["MIME-Version"] = "1.0"
+        # RFC 2387 §3 (multipart/related) - SOAP envelope is the root body part
+        headers["Content-Type"] = [
+          "multipart/related",
+          "type=\"#{SOAP_REQUEST_TYPE[@globals[:soap_version]]}\"",
+          "start=\"#{builder.multipart[:start]}\"",
+          "boundary=\"#{builder.multipart[:multipart_boundary]}\""
+        ].join("; ")
+        headers["MIME-Version"] = "1.0"
+        headers["Accept-Encoding"] = "gzip,deflate"
+      else
+        headers["Content-Type"] = CONTENT_TYPE[@globals[:soap_version]] % @globals[:encoding]
       end
 
-      # TODO: could HTTPI do this automatically in case the header
-      #       was not specified manually? [dh, 2013-01-04]
-      request.headers["Content-Length"] = request.body.bytesize.to_s
+      action = soap_action
+      headers["SOAPAction"] = %("#{action}") if action
 
-      request
+      headers
     end
 
+    # The resolved SOAPAction of the request, used for the HTTP header.
+    # {Savon::EffectiveOptions#soap_action} owns the precedence rules.
     def soap_action
-      # soap_action explicitly set to something falsy
-      return if @locals.include?(:soap_action) && !@locals[:soap_action]
-
-      # get the soap_action from local options
-      @locals[:soap_action] ||
-      # with no local option, but a wsdl, ask it for the soap_action
-      @wsdl.document? && @wsdl.soap_action(@name.to_sym) ||
-      # if there is no soap_action up to this point, fallback to a simple default
-      Gyoku.xml_tag(@name, :key_converter => @globals[:convert_request_keys_to])
+      effective_options.soap_action
     end
 
+    # The resolved endpoint URL the request is sent to.
+    # {Savon::EffectiveOptions#endpoint} owns the precedence rules.
     def endpoint
-      @globals[:endpoint] || @wsdl.endpoint.tap do |url|
-        if @globals[:host]
-          host_url = URI.parse(@globals[:host])
-          url.host = host_url.host
-          url.port = host_url.port
-        end
-      end
+      effective_options.endpoint
     end
 
-    def raise_expected_httpi_response!
-      raise Error, "Observers need to return an HTTPI::Response to mock " \
-                   "the request or nil to execute the request."
-    end
+    # Normalizes an observer return value into a Transport::Response.
+    #
+    # Accepts Transport::Response directly (current contract), wraps
+    # HTTPI::Response with a deprecation warning (legacy observer support),
+    # and raises on anything else.
+    def normalize_observer_response(observer_response)
+      return observer_response if observer_response.is_a?(Transport::Response)
+
+      if observer_response.is_a?(HTTPI::Response)
+        warn "Observers returning HTTPI::Response is deprecated - return Savon::Transport::Response instead.", uplevel: 1
+        return Transport::Response.from_httpi(observer_response)
+      end
 
+      raise Error, "Observers need to return a Savon::Transport::Response " \
+                   "to mock the request or nil to execute the request."
+    end
   end
 end