savon 0.6.8 → 0.7.0

data/CHANGELOG

@@ -1,3 +1,33 @@
+== 0.7.0 (2010-01-09)
+  This version comes with several changes to the public API!
+  Pay attention to the following list and read the updated Wiki: http://wiki.github.com/rubiii/savon
+
+  * Changed how Savon::WSDL can be disabled. Instead of disabling the WSDL globally/per request via two
+    different methods, you now simply append an exclamation mark (!) to your SOAP call: client.get_all_users!
+    Make sure you know what you're doing because when the WSDL is disabled, Savon does not know about which
+    SOAP actions are valid and just dispatches everything.
+  * The Net::HTTP object used by Savon::Request to retrieve WSDL documents and execute SOAP calls is now public.
+    While this makes the library even more flexible, it also comes with two major changes:
+    * SSL client authentication needs to be defined directly on the Net::HTTP object:
+      client.request.http.client_cert = ...
+      I added a shortcut method for setting all options through a Hash similar to the previous implementation:
+      client.request.http.ssl_client_auth :client_cert => ...
+    * Open and read timeouts also need to be set on the Net::HTTP object:
+      client.request.http.open_timeout = 30
+      client.request.http.read_timeout = 30
+    * Please refer to the Net::HTTP documentation for more details:
+      http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html
+  * Thanks to JulianMorrison, Savon now supports HTTP basic authentication:
+    client.request.http.basic_auth "username", "password"
+  * Julian also added a way to explicitly specify the order of Hash keys and values, so you should now be able
+    to work with services requiring a specific order of input parameters while still using Hash input.
+    For example: client.find_user { |soap| soap.body = { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }
+  * Savon::Response#to_hash now returns the content inside of "soap:Body" instead of trying to go one level
+    deeper and return it's content. The previous implementation only worked when the "soap:Body" element
+    contained a single child. See: http://github.com/rubiii/savon/issues#issue/17
+  * Added Savon::SOAP#namespace as a shortcut for setting the "xmlns:wsdl" namespace.
+    Usage example: soap.namespace = "http://example.com"
+
 == 0.6.8 (2010-01-01)
   * Improved specifications for various kinds of WSDL documents.
   * Added support for SOAP endpoints which are different than the WSDL endpoint of a service.

data/README.textile

@@ -4,6 +4,10 @@ h4. Heavy metal Ruby SOAP client library
 
 p. "RDoc":http://rdoc.info/projects/rubiii/savon | "Wiki":http://wiki.github.com/rubiii/savon | "ToDo":http://rubiii.tadalist.com/lists/1459816/public | "Metrics":http://getcaliper.com/caliper/project?repo=git://github.com/rubiii/savon.git
 
+h2. Warning
+
+p. Savon 0.7.0 comes with several changes to the public API. Pay attention to the CHANGELOG and the updated Wiki.
+
 h2. Installation
 
 bc. $ gem install savon
@@ -20,7 +24,7 @@ p. More information: "Client":http://wiki.github.com/rubiii/savon/client
 
 h2. Calling a SOAP action
 
-p. Assuming your service applies to the "Defaults":http://wiki.github.com/rubiii/savon/defaults, you can now call any available SOAP action.
+p. Assuming your service applies to the defaults, you can now call any available SOAP action.
 
 bc. response = client.get_all_users
 
@@ -67,5 +71,5 @@ More information: "Errors":http://wiki.github.com/rubiii/savon/errors
 
 h2. Logging
 
-p. Savon logs each request and response to STDOUT. But there are a couple of options to change the default behaviour.
+p. Savon logs each request and response to STDOUT. But there are a couple of options to change the default behavior.
 More information: "Logging":http://wiki.github.com/rubiii/savon/logging

data/Rakefile

@@ -1,24 +1,42 @@
-require "rubygems"
 require "rake"
 require "spec/rake/spectask"
 require "spec/rake/verify_rcov"
 require "rake/rdoctask"
 
-task :default => :spec_verify_rcov
+task :default => :spec_verify
 
 Spec::Rake::SpecTask.new do |spec|
-  spec.spec_files = FileList["spec/**/*_spec.rb"]
+  spec.spec_files = FileList["spec/{savon}/**/*_spec.rb"]
   spec.spec_opts << "--color"
   spec.libs += ["lib", "spec"]
   spec.rcov = true
   spec.rcov_dir = "rcov"
 end
 
-RCov::VerifyTask.new(:spec_verify_rcov => :spec) do |verify|
+RCov::VerifyTask.new(:spec_verify => :spec) do |verify|
   verify.threshold = 100.0
   verify.index_html = "rcov/index.html"
 end
 
+desc "Run integration specs using WEBrick"
+task :spec_integration do
+  pid = fork { exec "ruby spec/integration/server.rb" }
+  sleep 10 # wait until the server is actually ready
+  begin
+    task(:run_integration_spec).invoke
+  ensure
+    Process.kill "TERM", pid
+    Process.wait pid
+  end
+end
+
+desc "" # make this task invisible for "rake -T"
+Spec::Rake::SpecTask.new(:run_integration_spec) do |spec|
+  spec.spec_files = FileList["spec/{integration}/**/*_spec.rb"]
+  spec.spec_opts << "--color"
+  spec.libs += ["lib", "spec"]
+end
+
 Rake::RDocTask.new do |rdoc|
   rdoc.title = "Savon"
   rdoc.rdoc_dir = "rdoc"

data/lib/savon.rb

@@ -18,7 +18,7 @@ module Savon
 end
 
 # standard libs
-%w(logger net/http net/https openssl uri base64 digest/sha1 rexml/document).each do |lib|
+%w(logger net/https openssl base64 digest/sha1 rexml/document).each do |lib|
   require lib
 end
 

data/lib/savon/client.rb

@@ -6,19 +6,6 @@ module Savon
   # with SOAP services and XML.
   class Client
 
-    # Global setting of whether to use Savon::WSDL.
-    @@wsdl = true
-
-    # Sets the global setting of whether to use Savon::WSDL.
-    def self.wsdl=(wsdl)
-      @@wsdl = wsdl
-    end
-
-    # Returns the global setting of whether to use Savon::WSDL.
-    def self.wsdl?
-      @@wsdl
-    end
-
     # Expects a SOAP +endpoint+ String. Also accepts an optional Hash of
     # +options+ for specifying a proxy server and SSL client authentication.
     def initialize(endpoint, options = {})
@@ -26,17 +13,12 @@ module Savon
       @wsdl = WSDL.new @request
     end
 
-    # Accessor for Savon::WSDL.
-    attr_accessor :wsdl
+    # Returns the Savon::WSDL.
+    attr_reader :wsdl
 
     # Returns the Savon::Request.
     attr_reader :request
 
-    # Returns whether to use Savon::WSDL.
-    def wsdl?
-      self.class.wsdl? && @wsdl
-    end
-
     # Returns +true+ for available methods and SOAP actions.
     def respond_to?(method)
       return true if @wsdl.respond_to? method
@@ -47,22 +29,35 @@ module Savon
 
     # Dispatches requests to SOAP actions matching a given +method+ name.
     def method_missing(method, *args, &block) #:doc:
-      super if wsdl? && !@wsdl.respond_to?(method)
+      soap_call = soap_call_from method.to_s
+      super if @wsdl.enabled? && !@wsdl.respond_to?(soap_call)
 
-      setup_objects operation_from(method), &block
+      setup_objects operation_from(soap_call), &block
       Response.new @request.soap(@soap)
     end
 
+    # Sets whether to use Savon::WSDL by a given +method+ name and
+    # removes exclamation marks from the given +method+ name.
+    def soap_call_from(method)
+      if method[-1, 1] == "!"
+        @wsdl.enabled = false
+        method[0, method.length-1].to_sym
+      else
+        @wsdl.enabled = true
+        method.to_sym
+      end
+    end
+
     # Returns a SOAP operation Hash containing the SOAP action and input
-    # for a given +method+.
-    def operation_from(method)
-      return @wsdl.operations[method] if wsdl?
-      { :action => method.to_soap_key, :input => method.to_soap_key }
+    # for a given +soap_call+.
+    def operation_from(soap_call)
+      return @wsdl.operations[soap_call] if @wsdl.enabled?
+      { :action => soap_call.to_soap_key, :input => soap_call.to_soap_key }
     end
 
     # Returns the SOAP endpoint.
     def soap_endpoint
-      wsdl? ? @wsdl.soap_endpoint : @request.endpoint
+      @wsdl.enabled? ? @wsdl.soap_endpoint : @request.endpoint
     end
 
     # Expects a SOAP operation Hash and sets up Savon::SOAP and Savon::WSSE.
@@ -73,7 +68,7 @@ module Savon
 
       yield_objects &block if block
 
-      @soap.namespaces["xmlns:wsdl"] ||= @wsdl.namespace_uri if wsdl?
+      @soap.namespaces["xmlns:wsdl"] ||= @wsdl.namespace_uri if @wsdl.enabled?
       @soap.wsse = @wsse
     end
 

data/lib/savon/core_ext.rb

@@ -1,3 +1,3 @@
-%w(object string symbol datetime hash uri).each do |file|
+%w(object string symbol datetime hash uri net_http).each do |file|
   require File.dirname(__FILE__) + "/core_ext/#{file}"
 end

data/lib/savon/core_ext/hash.rb

@@ -1,29 +1,34 @@
 class Hash
 
-  # Expects an Array of Regexp Objects of which every Regexp recursively
-  # matches a key to be accessed. Returns the value of the last Regexp filter
-  # found in the Hash or an empty Hash in case the path of Regexp filters
-  # did not match the Hash structure.
-  def find_regexp(regexp)
-    regexp = [regexp] unless regexp.kind_of? Array
-    result = dup
-
-    regexp.each do |pattern|
-      result_key = result.keys.find { |key| key.to_s.match pattern }
-      result = result[result_key] ? result[result_key] : {}
-    end
-    result
+  # Error message for missing :@inorder elements.
+  InOrderMissing = "Missing elements in :@inorder %s"
+
+  # Error message for spurious :@inorder elements.
+  InOrderSpurious = "Spurious elements in :@inorder %s"
+
+  # Returns the values from the 'soap:Body' element or an empty Hash
+  # in case the node could not be found.
+  def find_soap_body
+    envelope = self[self.keys.first] || {}
+    body_key = envelope.keys.find { |key| /.+:Body/ =~ key } rescue nil
+    body_key ? envelope[body_key].map_soap_response : {}
   end
 
   # Returns the Hash translated into SOAP request compatible XML.
   #
-  # === Example
+  # To control the order of output, add a key of :@inorder with
+  # the value being an Array listing keys in order.
+  #
+  # === Examples
   #
   #   { :find_user => { :id => 666 } }.to_soap_xml
   #   => "<findUser><id>666</id></findUser>"
+  #
+  #   { :find_user => { :name => "Lucy", :id => 666, :@inorder => [:id, :name] } }.to_soap_xml
+  #   => "<findUser><id>666</id><name>Lucy</name></findUser>"
   def to_soap_xml
     @soap_xml = Builder::XmlMarkup.new
-    each { |key, value| nested_data_to_soap_xml key, value }
+    inorder(self).each { |key| nested_data_to_soap_xml key, self[key] }
     @soap_xml.target!
   end
 
@@ -49,14 +54,25 @@ private
   def nested_data_to_soap_xml(key, value)
     case value
       when Array
-        value.map { |sitem| nested_data_to_soap_xml key, sitem }
+        value.map { |subitem| nested_data_to_soap_xml key, subitem }
       when Hash
         @soap_xml.tag!(key.to_soap_key) do
-          value.each { |subkey, subvalue| nested_data_to_soap_xml subkey, subvalue }
+          inorder(value).each { |subkey| nested_data_to_soap_xml subkey, value[subkey] }
         end
       else
         @soap_xml.tag!(key.to_soap_key) { @soap_xml << value.to_soap_value }
     end
   end
 
+  # Takes a +hash+, removes the :@inorder marker and returns its keys.
+  # Raises an error in case an :@inorder Array does not match the Hash keys.
+  def inorder(hash)
+    inorder = hash.delete :@inorder
+    hash_keys = hash.keys
+    inorder = hash_keys unless inorder.kind_of? Array
+    raise InOrderMissing % (hash_keys - inorder).inspect unless (hash_keys - inorder).empty?
+    raise InOrderSpurious % (inorder - hash_keys).inspect unless (inorder - hash_keys).empty?
+    inorder
+  end
+
 end

data/lib/savon/core_ext/net_http.rb

@@ -0,0 +1,20 @@
+module Net
+  class HTTP
+
+    # Sets the endpoint +address+ and +port+.
+    def endpoint(address, port)
+      @address, @port = address, port
+    end
+
+    # Convenience method for setting SSL client authentication
+    # through a Hash of +options+.
+    def ssl_client_auth(options)
+      self.use_ssl = true
+      self.cert = options[:cert] if options[:cert]
+      self.key = options[:key] if options[:key]
+      self.ca_file = options[:ca_file] if options[:ca_file]
+      self.verify_mode = options[:verify_mode] if options[:verify_mode]
+    end
+
+  end
+end

data/lib/savon/request.rb

@@ -47,12 +47,11 @@ module Savon
       @@log_level
     end
 
-    # Expects a SOAP +endpoint+ String. Also accepts an optional Hash of
-    # +options+ for specifying a proxy server and SSL client authentication.
+    # 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("") 
-      @ssl = options[:ssl] if options[:ssl]
+      @proxy = options[:proxy] ? URI(options[:proxy]) : URI("")
     end
 
     # Returns the endpoint URI.
@@ -61,35 +60,45 @@ module Savon
     # Returns the proxy URI.
     attr_reader :proxy
 
-    # Accessor for HTTP open timeout.
-    attr_accessor :open_timeout
-
-    # Accessor for HTTP read timeout.
-    attr_accessor :read_timeout
+    # 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::HTTPResponse.
+    # Retrieves WSDL document and returns the Net::HTTP response.
     def wsdl
       log "Retrieving WSDL from: #{@endpoint}"
-      http.get @endpoint.to_s
+      http.endpoint @endpoint.host, @endpoint.port
+      http.use_ssl = @endpoint.ssl?
+      http.start { |h| h.request request(:wsdl) }
     end
 
     # Executes a SOAP request using a given Savon::SOAP instance and
-    # returns the Net::HTTPResponse.
+    # 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(@soap.endpoint).request_post @soap.endpoint.path, @soap.to_xml, http_header
+      @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 http_header.map { |key, value| "#{key}: #{value}" }.join( ", " )
+      log http_header.map { |key, value| "#{key}: #{value}" }.join(", ")
       log @soap.to_xml
     end
 
@@ -99,33 +108,22 @@ module Savon
       log @response.body
     end
 
-    # Returns a Net::HTTP instance for a given +endpoint+.
-    def http(endpoint = @endpoint)
-      @http = Net::HTTP::Proxy(@proxy.host, @proxy.port).new endpoint.host, endpoint.port
-      set_http_timeout
-      set_ssl_options endpoint.ssl?
-      set_ssl_authentication if @ssl
-      @http
-    end
-
-    # Sets HTTP open and read timeout.
-    def set_http_timeout
-      @http.open_timeout = @open_timeout if @open_timeout
-      @http.read_timeout = @read_timeout if @read_timeout
-    end
-
-    # Sets basic SSL options to the +@http+ instance.
-    def set_ssl_options(use_ssl)
-      @http.use_ssl = use_ssl
-      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    # 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 wsdl_endpoint
+        when :soap then Net::HTTP::Post.new @soap.endpoint.path, http_header
+      end
+      request.basic_auth *@basic_auth if @basic_auth
+      yield request if block_given?
+      request
     end
 
-    # Sets SSL client authentication to the +@http+ instance.
-    def set_ssl_authentication
-      @http.verify_mode = @ssl[:verify] if @ssl[:verify].kind_of? Integer
-      @http.cert = @ssl[:client_cert] if @ssl[:client_cert]
-      @http.key = @ssl[:client_key] if @ssl[:client_key]
-      @http.ca_file = @ssl[:ca_file] if @ssl[:ca_file]
+    # Returns the WSDL endpoint.
+    def wsdl_endpoint
+      return @endpoint.path unless @endpoint.query
+      "#{@endpoint.path}?#{@endpoint.query}"
     end
 
     # Returns a Hash containing the header for an HTTP request.
@@ -138,7 +136,7 @@ module Savon
       self.class.logger.send self.class.log_level, message if log?
     end
 
-    # Returns whether logging is possible.
+    # Returns whether to log.
     def log?
       self.class.log? && self.class.logger.respond_to?(self.class.log_level)
     end

data/lib/savon/response.rb

@@ -28,7 +28,7 @@ module Savon
 
     # Returns whether there was a SOAP fault.
     def soap_fault?
-      @soap_fault
+      @soap_fault ? true : false
     end
 
     # Returns the SOAP fault message.
@@ -36,15 +36,15 @@ module Savon
 
     # Returns whether there was an HTTP error.
     def http_error?
-      @http_error
+      @http_error ? true : false
     end
 
     # Returns the HTTP error message.
     attr_reader :http_error
 
-    # Returns the SOAP response as a Hash.
+    # Returns the SOAP response body as a Hash.
     def to_hash
-      @body.find_regexp(/.+/).map_soap_response
+      @body ||= Crack::XML.parse(@response.body).find_soap_body
     end
 
     # Returns the SOAP response XML.
@@ -52,45 +52,33 @@ module Savon
       @response.body
     end
 
-    alias :to_s  :to_xml
+    alias :to_s :to_xml
 
   private
 
-    # Returns the SOAP response body as a Hash.
-    def body
-      unless @body
-        body = Crack::XML.parse @response.body
-        @body = body.find_regexp [/.+:Envelope/, /.+:Body/]
-      end
-      @body
-    end
-
     # 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_message if self.class.raise_errors?
+        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
-      unless @soap_fault_message
-        soap_fault = body.find_regexp [/.+:Fault/]
-        @soap_fault_message = soap_fault_message_by_version(soap_fault)
-      end
-      @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)
-      if soap_fault.keys.include? "faultcode"
-        "(#{soap_fault['faultcode']}) #{soap_fault['faultstring']}"
-      elsif soap_fault.keys.include? "Code"
-        # SOAP 1.2 error code element is capitalized, see: http://www.w3.org/TR/soap12-part1/#faultcodeelement
-        "(#{soap_fault['Code']['Value']}) #{soap_fault['Reason']['Text']}"
+      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