hoopla-savon 0.7.6

data/lib/savon/logger.rb

@@ -0,0 +1,56 @@
+module Savon
+
+  # = Savon::Logger
+  #
+  # Savon::Logger can be mixed into classes to provide logging behavior.
+  #
+  # By default, the Logger mixin uses {Ruby's Logger}[http://ruby-doc.org/stdlib/libdoc/logger/rdoc/]
+  # from the standard library, a log level of :debug and is pointing to STDOUT.
+  module Logger
+
+    module ClassMethods
+
+      # Sets whether to log.
+      def log=(log)
+        @log = log
+      end
+
+      # Returns whether to log. Defaults to +true+.
+      def log?
+        @log != false
+      end
+
+      # Sets the logger.
+      def logger=(logger)
+        @logger = logger
+      end
+
+      # Returns the logger. Defaults to an instance of +Logger+ writing to STDOUT.
+      def logger
+        @logger ||= ::Logger.new STDOUT
+      end
+
+      # Sets the log level.
+      def log_level=(log_level)
+        @log_level = log_level
+      end
+
+      # Returns the log level. Defaults to +debug+.
+      def log_level
+        @log_level ||= :debug
+      end
+
+    end
+
+    # Extends the class including this module with its ClassMethods.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Logs a given +message+.
+    def log(message)
+      self.class.logger.send self.class.log_level, message if self.class.log?
+    end
+
+  end
+end

data/lib/savon/request.rb

@@ -0,0 +1,135 @@
+module Savon
+
+  # = Savon::Request
+  #
+  # Savon::Request handles both WSDL and SOAP requests.
+  #
+  # == The Net::HTTP object
+  #
+  # You can access the Net::HTTP object used for both WSDL and SOAP requests via:
+  #
+  #   client.request.http
+  #
+  # Here's an example of how to set open and read timeouts on the Net::HTTP object.
+  #
+  #   client.request.http.open_timeout = 30
+  #   client.request.http.read_timeout = 30
+  #
+  # Please refer to the {Net::HTTP documentation}[http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/]
+  # for more information.
+  #
+  # == HTTP basic authentication
+  #
+  # Setting credentials for HTTP basic authentication:
+  #
+  #   client.request.basic_auth "username", "password"
+  #
+  # == SSL client authentication
+  #
+  # You can use the methods provided by Net::HTTP to set SSL client authentication or use a shortcut:
+  #
+  #   client.request.http.ssl_client_auth(
+  #     :cert => OpenSSL::X509::Certificate.new(File.read("client_cert.pem")),
+  #     :key => OpenSSL::PKey::RSA.new(File.read("client_key.pem"), "password if one exists"),
+  #     :ca_file => "cacert.pem",
+  #     :verify_mode => OpenSSL::SSL::VERIFY_PEER
+  #   )
+  #
+  # == HTTP headers
+  #
+  # There's an accessor for the Hash of HTTP headers sent with any SOAP call:
+  #
+  #   client.request.headers["custom"] = "header"
+  class Request
+    include Logger
+
+    # Content-Types by SOAP version.
+    ContentType = { 1 => "text/xml;charset=UTF-8", 2 => "application/soap+xml;charset=UTF-8" }
+
+    # Expects a SOAP +endpoint+ String. Also accepts an optional Hash
+    # of +options+ for specifying a proxy server.
+    def initialize(endpoint, options = {})
+      @endpoint = URI endpoint
+      @proxy = options[:proxy] ? URI(options[:proxy]) : URI("")
+    end
+
+    # Returns the endpoint URI.
+    attr_reader :endpoint
+
+    # Returns the proxy URI.
+    attr_reader :proxy
+
+    # Returns the HTTP headers for a SOAP request.
+    def headers
+      @headers ||= {}
+    end
+
+    # Sets the HTTP headers for a SOAP request.
+    def headers=(headers)
+      @headers = headers if headers.kind_of? Hash
+    end
+
+    # Sets the +username+ and +password+ for HTTP basic authentication.
+    def basic_auth(username, password)
+      @basic_auth = [username, password]
+    end
+
+    # Retrieves WSDL document and returns the Net::HTTP response.
+    def wsdl
+      log "Retrieving WSDL from: #{@endpoint}"
+      Kernel.open(@endpoint.to_s)
+    end
+
+    # Executes a SOAP request using a given Savon::SOAP instance and returns the Net::HTTP response.
+    def soap(soap)
+      @soap = soap
+      http.endpoint @soap.endpoint.host, @soap.endpoint.port
+      http.use_ssl = @soap.endpoint.ssl?
+
+      log_request
+      @response = http.start do |h|
+        h.request request(:soap) { |request| request.body = @soap.to_xml }
+      end
+      log_response
+      @response
+    end
+
+    # Returns the Net::HTTP object.
+    def http
+      @http ||= Net::HTTP::Proxy(@proxy.host, @proxy.port).new @endpoint.host, @endpoint.port
+    end
+
+  private
+
+    # Logs the SOAP request.
+    def log_request
+      log "SOAP request: #{@soap.endpoint}"
+      log soap_headers.merge(headers).map { |key, value| "#{key}: #{value}" }.join(", ")
+      log @soap.to_xml
+    end
+
+    # Logs the SOAP response.
+    def log_response
+      log "SOAP response (status #{@response.code}):"
+      log @response.body
+    end
+
+    # Returns a Net::HTTP request for a given +type+. Yields the request to an optional block.
+    def request(type)
+      request = case type
+        when :wsdl then Net::HTTP::Get.new @endpoint.request_uri
+        when :soap then Net::HTTP::Post.new @soap.endpoint.request_uri, soap_headers.merge(headers)
+      end
+
+      request.basic_auth(*@basic_auth) if @basic_auth
+      yield request if block_given?
+      request
+    end
+
+    # Returns a Hash containing the SOAP headers for an HTTP request.
+    def soap_headers
+      { "Content-Type" => ContentType[@soap.version], "SOAPAction" => @soap.action }
+    end
+
+  end
+end

data/lib/savon/response.rb

@@ -0,0 +1,155 @@
+module Savon
+
+  # = Savon::Response
+  #
+  # Savon::Response represents both HTTP and SOAP response.
+  #
+  # == SOAP fault
+  #
+  # Assuming the default behavior of raising errors is disabled, you can ask the response object
+  # if there was a SOAP fault or an HTTP error and get the SOAP fault or HTTP error message.
+  #
+  #   response.soap_fault?
+  #   # => true
+  #
+  #   response.soap_fault
+  #   # => "(soap:Server) Fault occurred while processing."
+  #
+  #   response.http_error?
+  #   # => true
+  #
+  #   response.http_error
+  #   # => "Not found (404)"
+  #
+  # == Response as XML
+  #
+  # To get the raw SOAP response XML, you can call to_xml or to_s on the response object.
+  #
+  #   response.to_xml
+  #   => "<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  #   => "..."
+  #   => "</soap:Envelope>"
+  #
+  # == Response as a Hash
+  #
+  # You can also let Savon translate the SOAP response body to a Hash.
+  #
+  #   response.to_hash
+  #   => { :findUserByIdResponse => {
+  #   =>   :id => "123",
+  #   =>   :username => "eve"
+  #   =>   :active => true
+  #   => }
+  #
+  # When translating the SOAP response to a Hash, some XML tags and values are converted to more
+  # convenient Ruby objects. Translation is done through John Nunemaker's {Crack}[http://github.com/jnunemaker/crack]
+  # library along with some custom mapping.
+  #
+  # * XML tags (Hash keys) are converted to snake_case Symbols and namespaces are stripped off
+  # * SOAP xs:nil values are converted to nil objects
+  # * XML values specified in xs:DateTime format are converted to DateTime objects
+  # * XML values of "true" and "false" are converted to TrueClass and FalseClass
+  #
+  # == Net::HTTP response
+  #
+  # If for some reason you need to access the Net::HTTP response object ... you can.
+  #
+  #   bc. response.http
+  #   => #<Net::HTTPOK:0x7f749a1aa4a8>
+  class Response
+
+    # The maximum HTTP response code considered to be OK.
+    MaxNonErrorResponseCode = 299
+
+    # The global setting of whether to raise errors.
+    @@raise_errors = true
+
+    # Sets the global setting of whether to raise errors.
+    def self.raise_errors=(raise_errors)
+      @@raise_errors = raise_errors
+    end
+
+    # Returns the global setting of whether to raise errors.
+    def self.raise_errors?
+      @@raise_errors
+    end
+
+    # Expects a Net::HTTPResponse and handles errors.
+    def initialize(http)
+      @http = http
+
+      handle_soap_fault
+      handle_http_error
+    end
+
+    # Returns whether there was a SOAP fault.
+    def soap_fault?
+      !@soap_fault.blank?
+    end
+
+    # Returns the SOAP fault message.
+    attr_reader :soap_fault
+
+    # Returns whether there was an HTTP error.
+    def http_error?
+      !@http_error.blank?
+    end
+
+    # Returns the HTTP error message.
+    attr_reader :http_error
+
+    # Returns the SOAP response body as a Hash.
+    def to_hash
+      @body ||= (Crack::XML.parse(@http.body) rescue {}).find_soap_body
+    end
+
+    # Returns the SOAP response XML.
+    def to_xml
+      @http.body
+    end
+
+    # Returns the HTTP response object.
+    attr_reader :http
+
+    alias :to_s :to_xml
+
+  private
+
+    # Handles SOAP faults. Raises a Savon::SOAPFault unless the default behavior of raising errors
+    # was turned off.
+    def handle_soap_fault
+      if soap_fault_message
+        @soap_fault = soap_fault_message
+        raise Savon::SOAPFault, @soap_fault if self.class.raise_errors?
+      end
+    end
+
+    # Returns a SOAP fault message in case a SOAP fault was found.
+    def soap_fault_message
+      @soap_fault_message ||= soap_fault_message_by_version to_hash[:fault]
+    end
+
+    # Expects a Hash that might contain information about a SOAP fault. Returns the SOAP fault
+    # message in case one was found.
+    def soap_fault_message_by_version(soap_fault)
+      return unless soap_fault
+
+      if soap_fault.keys.include? :faultcode
+        "(#{soap_fault[:faultcode]}) #{soap_fault[:faultstring]}"
+      elsif soap_fault.keys.include? :code
+        "(#{soap_fault[:code][:value]}) #{soap_fault[:reason][:text]}"
+      end
+    end
+
+    # Handles HTTP errors. Raises a Savon::HTTPError unless the default behavior of raising errors
+    # was turned off.
+    def handle_http_error
+      if @http.code.to_i > MaxNonErrorResponseCode
+        @http_error = "#{@http.message} (#{@http.code})"
+        @http_error << ": #{@http.body}" unless @http.body.empty?
+        raise Savon::HTTPError, http_error if self.class.raise_errors?
+      end
+    end
+
+  end
+end

data/lib/savon/soap.rb

@@ -0,0 +1,302 @@
+module Savon
+
+  # = Savon::SOAP
+  #
+  # Savon::SOAP represents the SOAP request. Pass a block to your SOAP call and the SOAP object is
+  # passed to it as the first argument. The object allows setting the SOAP version, header, body
+  # and namespaces per request.
+  #
+  # == Body
+  #
+  # The body method lets you specify parameters to be received by the SOAP action.
+  #
+  # You can either pass in a hash (which will be translated to XML via Hash.to_soap_xml):
+  #
+  #   response = client.get_user_by_id do |soap|
+  #     soap.body = { :id => 123 }
+  #   end
+  #
+  # Or a string containing the raw XML:
+  #
+  #   response = client.get_user_by_id do |soap|
+  #     soap.body = "<id>123</id>"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Body>
+  #       <wsdl:getUserById><id>123</id></wsdl:getUserById>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # Please look at the documentation of Hash.to_soap_xml for some more information.
+  #
+  # == Version
+  #
+  # Savon defaults to SOAP 1.1. In case your service uses SOAP 1.2, you can use the version method
+  # to change the default per request.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.version = 2
+  #   end
+  #
+  # You can also change the default to SOAP 1.2 for all request:
+  #
+  #   Savon::SOAP.version = 2
+  #
+  # == Header
+  #
+  # If you need to add custom XML into the SOAP header, you can use the header method.
+  #
+  # The value is expected to be a hash (which will be translated to XML via Hash.to_soap_xml):
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.header["specialApiKey"] = "secret"
+  #   end
+  #
+  # Or a string containing the raw XML:
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.header = "<specialApiKey>secret</specialApiKey>"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Header>
+  #       <specialApiKey>secret</specialApiKey>
+  #     </env:Header>
+  #     <env:Body>
+  #       <wsdl:getAllUsers></wsdl:getAllUsers>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # == Namespaces
+  #
+  # The namespaces method contains a hash of attributes for the SOAP envelope. You can overwrite it
+  # or add additional attributes.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.namespaces["xmlns:domains"] = "http://domains.example.com"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
+  #       xmlns:domains="http://domains.example.com">
+  #     <env:Body>
+  #       <wsdl:getAllUsers></wsdl:getAllUsers>
+  #     </env:Body>
+  #   </env:Envelope>
+  #
+  # == Input
+  #
+  # You can change the name of the SOAP input tag in case you need to.
+  #
+  #   response = client.get_all_users do |soap|
+  #     soap.input = "GetAllUsersRequest"
+  #   end
+  #
+  # Request output:
+  #
+  #   <env:Envelope
+  #       xmlns:wsdl="http://example.com/user/1.0/UserService"
+  #       xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+  #     <env:Body>
+  #       <wsdl:GetAllUsersRequest></wsdl:GetAllUsersRequest>
+  #     </env:Body>
+  #   </env:Envelope>
+  class SOAP
+
+    # 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"
+    }
+
+    # Content-Types by SOAP version.
+    ContentType = { 1 => "text/xml", 2 => "application/soap+xml" }
+
+    # SOAP xs:dateTime format.
+    DateTimeFormat = "%Y-%m-%dT%H:%M:%SZ"
+
+    # SOAP xs:dateTime Regexp.
+    DateTimeRegexp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
+
+    # The global SOAP version.
+    @@version = 1
+
+    # Returns the global SOAP version.
+    def self.version
+      @@version
+    end
+
+    # Sets the global SOAP version.
+    def self.version=(version)
+      @@version = version if Versions.include? version
+    end
+
+    # Sets the global SOAP header. Expected to be a Hash that can be translated to XML via
+    # Hash.to_soap_xml or any other Object responding to to_s.
+    def self.header=(header)
+      @@header = header
+    end
+
+    # Returns the global SOAP header. Defaults to an empty Hash.
+    def self.header
+      @@header ||= {}
+    end
+
+    # Sets the global namespaces. Expected to be a Hash containing the namespaces (keys) and the
+    # corresponding URI's (values).
+    def self.namespaces=(namespaces)
+      @@namespaces = namespaces if namespaces.kind_of? Hash
+    end
+
+    # Returns the global namespaces. A Hash containing the namespaces (keys) and the corresponding
+    # URI's (values).
+    def self.namespaces
+      @@namespaces ||= {}
+    end
+
+    # Initialzes the SOAP object. Expects a SOAP +operation+ Hash along with an +endpoint+.
+    def initialize(action, input, endpoint)
+      @action, @input = action, input
+      @endpoint = endpoint.kind_of?(URI) ? endpoint : URI(endpoint)
+      @builder = Builder::XmlMarkup.new
+    end
+
+    # Sets the WSSE options.
+    attr_writer :wsse
+
+    # Sets the SOAP action.
+    attr_writer :action
+
+    # Returns the SOAP action.
+    def action
+      @action ||= ""
+    end
+
+    # Sets the SOAP input.
+    attr_writer :input
+
+    # Returns the SOAP input.
+    def input
+      @input ||= ""
+    end
+
+    # Accessor for the SOAP endpoint.
+    attr_accessor :endpoint
+
+    # Sets the SOAP header. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml
+    # or any other Object responding to to_s.
+    attr_writer :header
+
+    # Returns the SOAP header. Defaults to an empty Hash.
+    def header
+      @header ||= {}
+    end
+
+    # Accessor for the SOAP body. Expected to be a Hash that can be translated to XML via Hash.to_soap_xml
+    # or any other Object responding to to_s.
+    attr_accessor :body
+
+    # Accessor for overwriting the default SOAP request. Let's you specify completely custom XML.
+    attr_accessor :xml
+
+    # Sets the namespaces. Expected to be a Hash containing the namespaces (keys) and the
+    # corresponding URI's (values).
+    attr_writer :namespaces
+
+    # Returns the namespaces. A Hash containing the namespaces (keys) and the corresponding URI's
+    # (values). Defaults to a Hash containing an +xmlns:env+ key and the namespace for the current
+    # SOAP version.
+    def namespaces
+      @namespaces ||= { "xmlns:env" => Namespace[version] }
+    end
+
+    # Convenience method for setting the +xmlns:wsdl+ namespace.
+    def namespace=(namespace)
+      namespaces["xmlns:wsdl"] = namespace
+    end
+
+    # Sets the SOAP version.
+    def version=(version)
+      @version = version if Versions.include? version
+    end
+
+    # Returns the SOAP version. Defaults to the global default.
+    def version
+      @version ||= self.class.version
+    end
+
+    # Returns the SOAP envelope XML.
+    def to_xml
+      unless @xml
+        @builder.instruct!
+        @xml = @builder.env :Envelope, merged_namespaces do |xml|
+          xml.env(:Header) { xml << merged_header } unless merged_header.empty?
+          xml_body xml
+        end
+      end
+      @xml
+    end
+
+  private
+
+    # Returns a String containing the global and per request header.
+    def merged_header
+      if self.class.header.kind_of?(Hash) && header.kind_of?(Hash)
+        merged_header = self.class.header.merge(header).to_soap_xml
+      else
+        global_header = self.class.header.to_soap_xml rescue self.class.header.to_s
+        request_header = header.to_soap_xml rescue header.to_s
+        merged_header = global_header + request_header
+      end
+      merged_header + wsse_header
+    end
+
+    # Returns the WSSE header or an empty String in case WSSE was not set.
+    def wsse_header
+      @wsse.respond_to?(:header) ? @wsse.header : ""
+    end
+
+    # Adds a SOAP XML body to a given +xml+ Object.
+    def xml_body(xml)
+      xml.env(:Body) do
+        xml.tag!(:wsdl, *input_array) { xml << (@body.to_soap_xml rescue @body.to_s) }
+      end
+    end
+
+    # Returns a Hash containing the global and per request namespaces.
+    def merged_namespaces
+      self.class.namespaces.merge namespaces
+    end
+
+    # Returns an Array of SOAP input names to append to the wsdl namespace. Defaults to use the
+    # name of the SOAP action. May return an empty Array in case the specified SOAP input seems
+    # to be invalid.
+    def input_array
+      if input.kind_of?(Array) && !input.blank?
+        [input[0].to_sym, input[1]]
+      elsif !input.blank?
+        [input.to_sym]
+      elsif !action.blank?
+        [action.to_sym]
+      else
+        []
+      end
+    end
+
+  end
+end