savon 0.3.2 → 0.5.0

data/README.textile

@@ -0,0 +1,68 @@
+h1. Savon
+
+p. Savon can be installed as a gem via:
+
+bc. $ gem install savon
+
+h3. Dependencies
+
+bc. builder >= 2.1.2
+crack >= 0.1.4
+
+h2. Warning
+
+p. To use a heavy metal library like this, you have to be familiar with SOAP, WSDL and tools like soapUI.
+
+h2. First step
+
+p. Instantiate a new instance of Savon::Client, passing in the WSDL of your service.
+
+bc. proxy = Savon::Client.new "http://example.com/UserService?wsdl"
+
+h3. The WSDL
+
+p. You can find out about the SOAP actions available on the webservice by using the WSDL object.
+
+bc. proxy.wsdl.soap_actions
+=> [:get_all_users, :get_user_by_id, :user_magic]
+
+p. Find out more about the "WSDL":http://wiki.github.com/rubiii/savon/wsdl object.
+
+h3. Calling a SOAP action
+
+p. Now, assuming your service applies to the default "Options":http://wiki.github.com/rubiii/savon/options, you can just call any available SOAP action.
+
+bc. response = proxy.get_all_users
+
+p. Savon lets you call SOAP actions using snake_case, because even though they will propably be written in lowerCamelCase or CamelCase, it just feels much more natural.
+
+h3. Parameters
+
+p. Specifying parameters for the SOAP service, can be done by simply passing a Hash to the SOAP action.
+
+bc. response = proxy.get_user_by_id :id => 666
+
+p. Learn more about [[Parameters]].
+
+h3. The response
+
+p. By default, the SOAP response is translated into a Hash. Take a look at the "Options":http://wiki.github.com/rubiii/savon/options for more information.
+
+bc. proxy.get_user_by_id :id => 666
+=> { :user_response => { :id => "666", :username => "gorilla" } }
+
+h3. HTTP errors and SOAP faults
+
+p. Savon raises a Savon::SOAPFault in case of a SOAP fault and a Savon::HTTPError in case of an HTTP error. More information about "Errors":http://wiki.github.com/rubiii/savon/errors.
+
+h3. Logging
+
+p. By default Savon logs each request and response to STDOUT. Specifying your own logger is as easy as it gets:
+
+bc. Savon::Request.logger = RAILS_DEFAULT_LOGGER
+
+Read more about "Logging":http://wiki.github.com/rubiii/savon/logging.
+
+h3. RDoc and Wiki
+
+p. Further information: "Wiki":http://wiki.github.com/rubiii/savon and "RDoc":http://rdoc.info/projects/rubiii/savon

data/Rakefile

@@ -8,13 +8,15 @@ task :default => :spec
 Spec::Rake::SpecTask.new do |spec|
   spec.spec_files = FileList["spec/**/*_spec.rb"]
   spec.spec_opts << "--color"
+  spec.libs << "lib"
+  spec.rcov = true
+  spec.rcov_dir = "rcov"
 end
 
 Rake::RDocTask.new do |rdoc|
   rdoc.title = "Savon"
   rdoc.rdoc_dir = "rdoc"
-  rdoc.main = "README.rdoc"
-  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rdoc.rdoc_files.include("lib/**/*.rb")
   rdoc.options = ["--line-numbers", "--inline-source"]
 end
 
@@ -25,23 +27,23 @@ begin
     spec.author = "Daniel Harrington"
     spec.email = "me@rubiii.com"
     spec.homepage = "http://github.com/rubiii/savon"
-    spec.summary = "SOAP client library to enjoy"
+    spec.summary = "Heavy metal Ruby SOAP client library"
     spec.description = spec.summary
 
     spec.files = FileList["[A-Z]*", "{lib,spec}/**/*.{rb,xml}"]
 
     spec.rdoc_options += [
       "--title", "Savon",
-      "--main", "README.rdoc",
       "--line-numbers",
       "--inline-source"
     ]
 
-    spec.add_runtime_dependency("hpricot", "0.8.241")
-    spec.add_runtime_dependency("apricoteatsgorilla", "0.5.13")
+    spec.add_runtime_dependency("builder", ">= 2.1.2")
+    spec.add_runtime_dependency("crack", ">= 0.1.4")
 
     spec.add_development_dependency("rspec", ">= 1.2.8")
-    spec.add_development_dependency("rr", ">= 0.10.0")
+    spec.add_development_dependency("mocha", ">= 0.9.7")
+    spec.add_development_dependency("fakeweb", ">= 1.2.7")
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.5.0

data/lib/savon.rb

@@ -1,44 +1,43 @@
 module Savon
 
-  # Raised by the <tt>on_http_error</tt> method in case of an HTTP error.
-  # <tt>on_http_error</tt> may be overwritten to customize error handling.
-  class HTTPError < StandardError; end
-
-  # Raised by the <tt>on_soap_fault</tt> method in case of a SOAP fault.
-  # <tt>on_soap_fault</tt> may be overwritten to customize error handling.
-  class SOAPFault < StandardError; end
-
-  # The logger to use.
-  @@logger = nil
+  # Current version.
+  VERSION = "0.5.0"
 
-  # The log level to use.
-  @@log_level = :debug
+  # Supported SOAP versions.
+  SOAPVersions = [1, 2]
 
-  # Sets the logger to use.
-  def self.logger=(logger)
-    @@logger = logger
-  end
+  # SOAP xs:dateTime format.
+  SOAPDateTimeFormat = "%Y-%m-%dT%H:%M:%S"
 
-  # Sets the log level to use.
-  def self.log_level=(log_level)
-    @@log_level = log_level
-  end
+  # SOAP xs:dateTime Regexp.
+  SOAPDateTimeRegexp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/
 
-  # Logs a given +message+ using the +@@logger+ instance or yields the logger
-  # to a given +block+ for logging multiple messages at once.
-  def self.log(message = nil)
-    if @@logger
-      @@logger.send(@@log_level, message) if message
-      yield @@logger if block_given?
-    end
-  end
+  # Raised in case of an HTTP error.
+  class HTTPError < StandardError; end
 
-end
+  # Raised in case of a SOAP fault.
+  class SOAPFault < StandardError; end
 
-%w(net/http net/https uri rubygems hpricot apricoteatsgorilla).each do |gem|
-  require gem
 end
 
-%w(service wsdl).each do |file|
-  require File.join(File.dirname(__FILE__), "savon", file)
-end
+# stdlib
+require "logger"
+require "net/http"
+require "net/https"
+require "uri"
+require "base64"
+require "digest/sha1"
+require "rexml/document"
+
+# gems
+require "builder"
+require "crack/xml"
+
+# savon
+require "savon/core_ext"
+require "savon/validation"
+require "savon/wsse"
+require "savon/soap"
+require "savon/request"
+require "savon/wsdl"
+require "savon/client"

data/lib/savon/client.rb

@@ -0,0 +1,96 @@
+module Savon
+
+  # == Savon::Client
+  #
+  # Heavy metal Ruby SOAP client library. Minimizes the overhead of working
+  # with SOAP services and XML.
+  class Client
+    include Validation
+
+    # Default behavior for processing the SOAP response. Expects an instance
+    # of Net::HTTPResponse and returns the SOAP response body as a Hash.
+    @response_process = lambda do |response|
+      response_hash = Crack::XML.parse response.body
+      error_handling.call response, response_hash
+
+      response_hash = response_hash["soap:Envelope"]["soap:Body"]
+      response_hash = response_hash[response_hash.keys.first]
+      (response_hash["return"] || response_hash).map_soap_response
+    end
+
+    # Default error handling. Expects an instance of Net::HTTPResponse and
+    # a SOAP response body Hash. Raises a Savon::SOAPFault in case of a SOAP
+    # fault or a Savon::HTTPError in case of an HTTP error.
+    @error_handling = lambda do |response, response_hash|
+      soap_fault = response_hash.to_soap_fault_message
+      raise Savon::SOAPFault, soap_fault if soap_fault
+
+      http_error = "#{response.message} (#{response.code})"
+      http_error += ": #{response.body}" unless response.body.empty?
+      raise Savon::HTTPError, http_error if response.code.to_i >= 300
+    end
+
+    class << self
+
+      # Accessor for the default response block.
+      attr_accessor :response_process
+
+      # Accessor for the default error handling.
+      attr_accessor :error_handling
+
+    end
+
+    # Expects a SOAP +endpoint+ String.
+    def initialize(endpoint)
+      @request = Request.new endpoint
+      @wsdl = WSDL.new @request
+    end
+
+    # Returns the Savon::WSDL.
+    attr_reader :wsdl
+
+    # Returns the Net::HTTPResponse of the last SOAP request.
+    attr_reader :response
+
+    # Behaves as usual, but also returns +true+ for available SOAP actions.
+    def respond_to?(method)
+      return true if @wsdl.soap_actions.include? method
+      super
+    end
+
+  private
+
+    # Behaves as usual, but dispatches SOAP requests to SOAP actions matching
+    # the given +method+ name.
+    def method_missing(method, *args, &block) #:doc:
+      soap_action = @wsdl.mapped_soap_actions[method]
+      super unless soap_action
+
+      soap_body, options = args[0] || {}, args[1] || {}
+      validate_arguments! soap_body, options, block
+      dispatch soap_action, soap_body, options, block
+    end
+
+    # Dispatches a given +soap_action+ with a given +soap_body+, +options+
+    # and a +block+.
+    def dispatch(soap_action, soap_body, options, block = nil)
+      @soap = SOAP.new soap_action, soap_body, options, @wsdl.namespace_uri
+      @response = @request.soap @soap
+      response_process(block).call @response
+    end
+
+    # Returns the response process to use.
+    def response_process(block)
+      block || self.class.response_process
+    end
+
+    # Validates the given +soap_body+, +options+ and +response_process+.
+    def validate_arguments!(soap_body, options = {}, response_process = nil)
+      validate! :soap_body, soap_body if soap_body
+      validate! :response_process, response_process if response_process
+      validate! :soap_version, options[:soap_version] if options[:soap_version]
+      validate! :wsse_credentials, options[:wsse] if options[:wsse].kind_of? Hash
+    end
+
+  end
+end

data/lib/savon/core_ext.rb

@@ -0,0 +1,6 @@
+require "savon/core_ext/object"
+require "savon/core_ext/string"
+require "savon/core_ext/symbol"
+require "savon/core_ext/datetime"
+require "savon/core_ext/hash"
+require "savon/core_ext/uri"

data/lib/savon/core_ext/datetime.rb

@@ -0,0 +1,8 @@
+class DateTime
+
+  # Returns the DateTime as an xs:dateTime formatted String.
+  def to_soap_value
+    strftime Savon::SOAPDateTimeFormat
+  end
+
+end

data/lib/savon/core_ext/hash.rb

@@ -0,0 +1,65 @@
+class Hash
+
+  # Returns the Hash translated into SOAP request compatible XML.
+  #
+  # === Example
+  #
+  #   { :find_user => { :id => 666 } }.to_soap_xml
+  #   => "<findUser><id>666</id></findUser>"
+  def to_soap_xml
+    @soap_xml = Builder::XmlMarkup.new
+    each { |key, value| nested_data_to_soap_xml key, value }
+    @soap_xml.target!
+  end
+
+  # Tries to generate a SOAP fault message from the Hash. Returns nil in
+  # case no SOAP fault could be found or generated.
+  def to_soap_fault_message
+    soap_fault = self["soap:Envelope"]["soap:Body"]["soap:Fault"] rescue {}
+    return nil 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']}"
+    else
+      nil
+    end
+  end
+
+  # Maps keys and values of a Hash created from SOAP response XML to
+  # more convenient Ruby Objects.
+  def map_soap_response
+    inject({}) do |hash, (key, value)|
+      key = key.strip_namespace.snakecase.to_sym
+
+      value = case value
+        when Hash
+          value["xsi:nil"] ? nil : value.map_soap_response
+        when Array
+          value.map { |a_value| a_value.map_soap_response rescue a_value }
+        when String
+          value.map_soap_response
+      end
+      hash.merge key => value
+    end
+  end
+
+private
+
+  # Expects a Hash +key+ and +value+ and recursively creates an XML structure
+  # representing the Hash content.
+  def nested_data_to_soap_xml(key, value)
+    case value
+      when Array
+        value.map { |sitem| nested_data_to_soap_xml key, sitem }
+      when Hash
+        @soap_xml.tag!(key.to_soap_key) do
+          value.each { |subkey, subvalue| nested_data_to_soap_xml subkey, subvalue }
+        end
+      else
+        @soap_xml.tag!(key.to_soap_key) { @soap_xml << value.to_soap_value }
+    end
+  end
+
+end

data/lib/savon/core_ext/object.rb

@@ -0,0 +1,14 @@
+class Object
+
+  # Returns the Object as a SOAP request compliant key.
+  def to_soap_key
+    to_s
+  end
+
+  # Returns the Object as a SOAP request compliant value.
+  def to_soap_value
+    return to_s unless respond_to? :to_datetime
+    to_datetime.to_soap_value
+  end
+
+end

data/lib/savon/core_ext/string.rb

@@ -0,0 +1,41 @@
+class String
+
+  # Returns the String in snake_case.
+  def snakecase
+    str = dup
+    str.gsub! /::/, '/'
+    str.gsub! /([A-Z]+)([A-Z][a-z])/, '\1_\2'
+    str.gsub! /([a-z\d])([A-Z])/, '\1_\2'
+    str.tr! "-", "_"
+    str.downcase!
+    str
+  end
+
+  # Returns the String in lowerCamelCase.
+  def lower_camelcase
+    str = dup
+    str.gsub!(/\/(.?)/) { "::#{$1.upcase}" }
+    str.gsub!(/(?:_+|-+)([a-z])/) { $1.upcase }
+    str.gsub!(/(\A|\s)([A-Z])/) { $1 + $2.downcase }
+    str
+  end
+
+  # Returns the String without namespace.
+  def strip_namespace
+    gsub /(.+:)(.+)/, '\2'
+  end
+
+  # Translates SOAP response values to more convenient Ruby Objects.
+  def map_soap_response
+    return DateTime.parse self if Savon::SOAPDateTimeRegexp === self
+    return true if self.strip.downcase == "true"
+    return false if self.strip.downcase == "false"
+    self
+  end
+
+  # Returns the String as a SOAP request compliant value.
+  def to_soap_value
+    to_s
+  end
+
+end

data/lib/savon/core_ext/symbol.rb

@@ -0,0 +1,8 @@
+class Symbol
+
+  # Returns the Symbol as a lowerCamelCase String.
+  def to_soap_key
+    to_s.lower_camelcase
+  end
+
+end

data/lib/savon/core_ext/uri.rb

@@ -0,0 +1,10 @@
+module URI
+  class HTTP
+
+    # Returns whether the URI hints to SSL.
+    def ssl?
+      /^https/ === @scheme
+    end
+
+  end
+end