regenersis-savon 1.0.0

data/lib/savon/hooks/hook.rb

@@ -0,0 +1,36 @@
+module Savon
+  module Hooks
+
+    # = Savon::Hooks::Hook
+    #
+    # A hook used somewhere in the system.
+    class Hook
+
+      HOOKS = [
+
+        # Replaces the POST request executed to call a service.
+        # See: Savon::SOAP::Request#response
+        #
+        # Receives the <tt>Savon::SOAP::Request</tt> and is expected to return an <tt>HTTPI::Response</tt>.
+        # It can change the request and return something falsy to still execute the POST request.
+        :soap_request
+
+      ]
+
+      # Expects an +id+, the name of the +hook+ to use and a +block+ to be called.
+      def initialize(id, hook, &block)
+        self.id = id
+        self.hook = hook
+        self.block = block
+      end
+
+      attr_accessor :id, :hook, :block
+
+      # Calls the +block+ with the given +args+.
+      def call(*args)
+        block.call(*args)
+      end
+
+    end
+  end
+end

data/lib/savon/http/error.rb

@@ -0,0 +1,42 @@
+require "savon/error"
+require "savon/soap/xml"
+
+module Savon
+  module HTTP
+
+    # = Savon::HTTP::Error
+    #
+    # Represents an HTTP error. Contains the original <tt>HTTPI::Response</tt>.
+    class Error < Error
+
+      # Expects an <tt>HTTPI::Response</tt>.
+      def initialize(http)
+        self.http = http
+      end
+
+      # Accessor for the <tt>HTTPI::Response</tt>.
+      attr_accessor :http
+
+      # Returns whether an HTTP error is present.
+      def present?
+        http.error?
+      end
+
+      # Returns the HTTP error message.
+      def to_s
+        return "" unless present?
+        
+        @message ||= begin
+          message = "HTTP error (#{http.code})"
+          message << ": #{http.body}" unless http.body.empty?
+        end
+      end
+
+      # Returns the HTTP response as a Hash.
+      def to_hash
+        @hash = { :code => http.code, :headers => http.headers, :body => http.body }
+      end
+
+    end
+  end
+end

data/lib/savon/model.rb

@@ -0,0 +1,103 @@
+module Savon
+
+  # = Savon::Model
+  #
+  # Model for SOAP service oriented applications.
+  module Model
+
+    def self.extended(base)
+      base.setup
+    end
+
+    def setup
+      class_action_module
+      instance_action_module
+    end
+
+    # Accepts one or more SOAP actions and generates both class and instance methods named
+    # after the given actions. Each generated method accepts an optional SOAP body Hash and
+    # a block to be passed to <tt>Savon::Client#request</tt> and executes a SOAP request.
+    def actions(*actions)
+      actions.each do |action|
+        define_class_action(action)
+        define_instance_action(action)
+      end
+    end
+
+  private
+
+    # Defines a class-level SOAP action method.
+    def define_class_action(action)
+      class_action_module.module_eval %{
+        def #{action.to_s.snakecase}(body = nil, &block)
+          response = client.request :wsdl, #{action.inspect}, :body => body, &block
+          Savon.hooks.select(:model_soap_response).call(response) || response
+        end
+      }
+    end
+
+    # Defines an instance-level SOAP action method.
+    def define_instance_action(action)
+      instance_action_module.module_eval %{
+        def #{action.to_s.snakecase}(body = nil, &block)
+          self.class.#{action.to_s.snakecase} body, &block
+        end
+      }
+    end
+
+    # Class methods.
+    def class_action_module
+      @class_action_module ||= Module.new do
+
+        # Returns the memoized <tt>Savon::Client</tt>.
+        def client(&block)
+          @client ||= Savon::Client.new(&block)
+        end
+
+        # Sets the SOAP endpoint to the given +uri+.
+        def endpoint(uri)
+          client.wsdl.endpoint = uri
+        end
+
+        # Sets the target namespace.
+        def namespace(uri)
+          client.wsdl.namespace = uri
+        end
+
+        # Sets the WSDL document to the given +uri+.
+        def document(uri)
+          client.wsdl.document = uri
+        end
+
+        # Sets the HTTP headers.
+        def headers(headers)
+          client.http.headers = headers
+        end
+
+        # Sets basic auth +login+ and +password+.
+        def basic_auth(login, password)
+          client.http.auth.basic(login, password)
+        end
+
+        # Sets WSSE auth credentials.
+        def wsse_auth(*args)
+          client.wsse.credentials(*args)
+        end
+
+      end.tap { |mod| extend(mod) }
+    end
+
+    # Instance methods.
+    def instance_action_module
+      @instance_action_module ||= Module.new do
+
+        # Returns the <tt>Savon::Client</tt> from the class instance.
+        def client(&block)
+          self.class.client(&block)
+        end
+
+      end.tap { |mod| include(mod) }
+    end
+
+  end
+end

data/lib/savon/soap.rb

@@ -0,0 +1,21 @@
+module Savon
+
+  # = Savon::SOAP
+  #
+  # Contains various SOAP details.
+  module SOAP
+
+    # Default SOAP version.
+    DefaultVersion = 1
+
+    # Supported SOAP versions.
+    Versions = 1..2
+
+    # SOAP namespaces by SOAP version.
+    Namespace = {
+      1 => "http://schemas.xmlsoap.org/soap/envelope/",
+      2 => "http://www.w3.org/2003/05/soap-envelope"
+    }
+
+  end
+end

data/lib/savon/soap/fault.rb

@@ -0,0 +1,59 @@
+require "savon/error"
+require "savon/soap/xml"
+
+module Savon
+  module SOAP
+
+    # = Savon::SOAP::Fault
+    #
+    # Represents a SOAP fault. Contains the original <tt>HTTPI::Response</tt>.
+    class Fault < Error
+
+      # Expects an <tt>HTTPI::Response</tt>.
+      def initialize(http)
+        self.http = http
+      end
+
+      # Accessor for the <tt>HTTPI::Response</tt>.
+      attr_accessor :http
+
+      # Returns whether a SOAP fault is present.
+      def present?
+        @present ||= http.body.include?("Fault>") && (soap1_fault? || soap2_fault?)
+      end
+
+      # Returns the SOAP fault message.
+      def to_s
+        return "" unless present?
+        @message ||= message_by_version to_hash[:fault]
+      end
+
+      # Returns the SOAP response body as a Hash.
+      def to_hash
+        @hash ||= Nori.parse(http.body)[:envelope][:body]
+      end
+
+    private
+
+      # Returns whether the response contains a SOAP 1.1 fault.
+      def soap1_fault?
+        http.body.include?("faultcode>") && http.body.include?("faultstring>")
+      end
+
+      # Returns whether the response contains a SOAP 1.2 fault.
+      def soap2_fault?
+        http.body.include?("Code>") && http.body.include?("Reason>")
+      end
+
+      # Returns the SOAP fault message by version.
+      def message_by_version(fault)
+        if fault[:faultcode]
+          "(#{fault[:faultcode]}) #{fault[:faultstring]}"
+        elsif fault[:code]
+          "(#{fault[:code][:value]}) #{fault[:reason][:text]}"
+        end
+      end
+
+    end
+  end
+end

data/lib/savon/soap/request.rb

@@ -0,0 +1,71 @@
+require "httpi"
+require "savon/soap/response"
+
+module Savon
+  module SOAP
+
+    # = Savon::SOAP::Request
+    #
+    # Executes SOAP requests.
+    class Request
+
+      # Content-Types by SOAP version.
+      ContentType = { 1 => "text/xml;charset=UTF-8", 2 => "application/soap+xml;charset=UTF-8" }
+
+      # Expects an <tt>HTTPI::Request</tt> and a <tt>Savon::SOAP::XML</tt> object
+      # to execute a SOAP request and returns the response.
+      def self.execute(http, soap)
+        new(http, soap).response
+      end
+
+      # Expects an <tt>HTTPI::Request</tt> and a <tt>Savon::SOAP::XML</tt> object.
+      def initialize(http, soap)
+        self.soap = soap
+        self.http = configure(http)
+      end
+
+      attr_accessor :soap, :http
+
+      # Executes the request and returns the response.
+      def response
+        @response ||= SOAP::Response.new(
+          Savon.hooks.select(:soap_request).call(self) || with_logging { HTTPI.post(http) }
+        )
+      end
+
+    private
+
+      # Configures a given +http+ from the +soap+ object.
+      def configure(http)
+        http.url = soap.endpoint
+        http.body = soap.to_xml
+        http.headers["Content-Type"] ||= ContentType[soap.version]
+        http.headers["Content-Length"] ||= soap.to_xml.length.to_s
+
+        http
+      end
+
+      # Logs the HTTP request, yields to a given +block+ and returns a <tt>Savon::SOAP::Response</tt>.
+      def with_logging
+        log_request http.url, http.headers, http.body
+        response = yield
+        log_response response.code, response.body
+        response
+      end
+
+      # Logs the SOAP request +url+, +headers+ and +body+.
+      def log_request(url, headers, body)
+        Savon.log "SOAP request: #{url}"
+        Savon.log headers.map { |key, value| "#{key}: #{value}" }.join(", ")
+        Savon.log body
+      end
+
+      # Logs the SOAP response +code+ and +body+.
+      def log_response(code, body)
+        Savon.log "SOAP response (status #{code}):"
+        Savon.log body
+      end
+
+    end
+  end
+end

data/lib/savon/soap/response.rb

@@ -0,0 +1,109 @@
+require "savon/soap/xml"
+require "savon/soap/fault"
+require "savon/http/error"
+
+module Savon
+  module SOAP
+
+    # = Savon::SOAP::Response
+    #
+    # Represents the SOAP response and contains the HTTP response.
+    class Response
+
+      # Expects an <tt>HTTPI::Response</tt> and handles errors.
+      def initialize(response)
+        self.http = response
+        raise_errors if Savon.raise_errors?
+      end
+
+      attr_accessor :http
+
+      # Returns whether the request was successful.
+      def success?
+        !soap_fault? && !http_error?
+      end
+
+      # Returns whether there was a SOAP fault.
+      def soap_fault?
+        soap_fault.present?
+      end
+
+      # Returns the <tt>Savon::SOAP::Fault</tt>.
+      def soap_fault
+        @soap_fault ||= Fault.new http
+      end
+
+      # Returns whether there was an HTTP error.
+      def http_error?
+        http_error.present?
+      end
+
+      # Returns the <tt>Savon::HTTP::Error</tt>.
+      def http_error
+        @http_error ||= HTTP::Error.new http
+      end
+
+      # Shortcut accessor for the SOAP response body Hash.
+      def [](key)
+        body[key]
+      end
+
+      # Returns the SOAP response header as a Hash.
+      def header
+        hash[:envelope][:header]
+      end
+
+      # Returns the SOAP response body as a Hash.
+      def body
+        hash[:envelope][:body]
+      end
+
+      alias to_hash body
+
+      # Traverses the SOAP response body Hash for a given +path+ of Hash keys and returns
+      # the value as an Array. Defaults to return an empty Array in case the path does not
+      # exist or returns nil.
+      def to_array(*path)
+        result = path.inject body do |memo, key|
+          return [] unless memo[key]
+          memo[key]
+        end
+
+        result.kind_of?(Array) ? result.compact : [result].compact
+      end
+
+      # Returns the complete SOAP response XML without normalization.
+      def hash
+        @hash ||= Nori.parse(to_xml)
+      end
+
+      # Returns the SOAP response XML.
+      def to_xml
+        http.body
+      end
+
+      # Returns a <tt>Nokogiri::XML::Document</tt> for the SOAP response XML.
+      def doc
+        @doc ||= Nokogiri::XML(to_xml)
+      end
+
+      # Returns an Array of <tt>Nokogiri::XML::Node</tt> objects retrieved with the given +path+.
+      # Automatically adds all of the document's namespaces unless a +namespaces+ hash is provided.
+      def xpath(path, namespaces = nil)
+        doc.xpath(path, namespaces || xml_namespaces)
+      end
+
+    private
+
+      def raise_errors
+        raise soap_fault if soap_fault?
+        raise http_error if http_error?
+      end
+
+      def xml_namespaces
+        @xml_namespaces ||= doc.collect_namespaces
+      end
+
+    end
+  end
+end