digitaria-handsoap 0.1.3

data/README.markdown

@@ -0,0 +1,227 @@
+Handsoap
+===
+
+What
+---
+Handsoap is a library for creating SOAP clients in Ruby.
+
+[Watch a tutorial](http://www.vimeo.com/4813848), showing how to use Handsoap. The final application can be found at: [http://github.com/troelskn/handsoap-example/tree/master](http://github.com/troelskn/handsoap-example/tree/master)
+
+![Handsoap](http://ny-image0.etsy.com/il_430xN.68558416.jpg)
+
+Why
+---
+
+Ruby already has a SOAP-client library, [soap4r](http://dev.ctor.org/soap4r), so why create another one?
+
+> Let me summarize SOAP4R: it smells like Java code built on a Monday morning by an EJB coder.
+>
+> -- [Ruby In Practice: REST, SOAP, WebSphere MQ and SalesForce](http://blog.labnotes.org/2008/01/28/ruby-in-practice-rest-soap-websphere-mq-and-salesforce/)
+
+OK, not entirely fair, but soap4r has problems. It's incomplete and buggy. If you try to use it for any real-world services, you quickly run into compatibility issues. You can get around some of them, if you have control over the service, but you may not always be that lucky. In the end, even if you get it working, it has a bulky un-Rubyish feel to it.
+
+Handsoap tries to do better by taking a minimalistic approach. Instead of a full abstraction layer, it is more like a toolbox with which you can write SOAP bindings. You could think of it as a [ffi](http://c2.com/cgi/wiki?ForeignFunctionInterface) targeting SOAP.
+
+This means that you generally need to do more manual labor in the cases where soap4r would have automated the mapping. It also means that you need to get your hands dirty with wsdl, xsd and other heavyweight specifications. However, it does give you some tools to help you stay sane.
+
+There are several benefits of using Handsoap:
+
+* It supports the entire SOAP specification, all versions (because you have to implement it your self).
+* You actually get a sporting chance to debug and fix protocol level bugs.
+* It's much faster than soap4r, because it uses fast low-level libraries for xml-parsing and http-communication.
+
+To summarise, soap4r takes an optimistic approach, where Handsoap expects things to fail. If soap4r works for you today, it's probably the better choice. If you find your self strugling with it, Handsoap will offer a more smooth ride. It won't magically fix things for you though.
+
+Handsoap vs. soap4r benchmark
+---
+
+Benchmarks are always unfair, but my experiments has placed Handsoap at being approximately double as fast as soap4r. I'd love any suggestions for a more precise measure.
+
+    $ ruby tests/benchmark_test.rb 1000
+    Benchmarking 1000 calls ...
+                    user     system      total        real
+    handsoap    0.750000   0.090000   0.840000 (  1.992437)
+    soap4r      2.240000   0.140000   2.380000 (  3.605836)
+    ---------------
+    Legend:
+    The user CPU time, system CPU time, the sum of the user and system CPU times,
+    and the elapsed real time. The unit of time is seconds.
+
+SOAP basics
+---
+
+SOAP is a protocol that is tunneled through XML over HTTP. Apart from using the technology for transportation, it doesn't have much to do with HTTP. Some times, it hasn't even got much to do with XML either.
+
+A SOAP client basically consists of three parts:
+
+* A http-connectivity layer,
+* a mechanism for marshalling native data types to XML,
+* and a mechanism for unmarshalling XML to native data types.
+
+The protocol also contains a large and unwieldy specification of how to do the (un)marshalling, which can be used as the basis for automatically mapping to a rich type model. This makes the protocol fitting for .net/Java, but is a huge overhead for a very dynamically typed language such as Ruby. Much of the complexity of clients such as soap4r, is in the parts that tries to use this specification. Handsoap expects you to manually write the code that marshals/unmarshals, thereby bypassing this complexity (or rather - pass it to the programmer)
+
+Handsoap only supports RPC-style SOAP. This seems to be the most common style. It's probably possible to add support for Document-style with little effort, but until I see the need I'm not going there.
+
+The toolbox
+---
+
+The Handsoap toolbox consists of the following components.
+
+Handsoap can use either [curb](http://curb.rubyforge.org/) or [httpclient](http://dev.ctor.org/http-access2) for HTTP-connectivity. The former is recommended, and default, but for portability you might choose the latter. You usually don't need to interact at the HTTP-level, but if you do (for example, if you have to use SSL), you can.
+
+For parsing XML, Handsoap uses [Nokogiri](http://github.com/tenderlove/nokogiri/tree/master). While this may become optional in the future, the dependency is a bit tighter. The XML-parser is used internally in Handsoap, as well as by the code that maps from SOAP to Ruby (The code you're writing). Nokogiri is very fast (being based om libxml) and has a polished and stable api.
+
+There is also a library for generating XML, which you'll use when mapping from Ruby to SOAP. It's quite similar to [Builder](http://builder.rubyforge.org/), but is tailored towards being used for writing SOAP-messages. The name of this library is `XmlMason` and it is included/part of Handsoap.
+
+Recommendations
+---
+
+###Workflow
+
+1. Find the wsdl for the service you want to consume.
+
+2. Figure out the url for the endpoint, as well as the protocol version. Put this in a config file.
+	 * To find the endpoint, look inside the wsdl, for `<soap:address location="..">`
+
+3. Create a service class. Add endpoints and protocol. Alias needed namespace(s).
+   * To find the namespace(s), look in the samples from soapUI. It will be imported as `v1`
+
+4. Open the wsdl in [soapUI](http://www.soapui.org/).
+
+5. In soapUI, find a sample request for the method you want to use. Copy+paste the body-part.
+
+6. Create a method in your service class (Use ruby naming convention)
+
+7. Write Ruby-code (using XmlMason) to generate a request that is similar to the example from soapUI. (In your copy+paste buffer)
+
+8. Write Ruby-code to parse the response (a Nokogiri XML-document) into Ruby data types.
+
+9. Write an integration test to verify that your method works as expected. You can use soapUI to [generate a mock-service](http://www.soapui.org/userguide/mock/getting_started.html).
+
+Repeat point 5..9 for each method that you need to use.
+Between each iteration, you should refactor shared code into helper functions.
+
+###Configuration
+
+If you use Rails, you should put the endpoint in a constant in the environment file. That way, you can have different endpoints for test/development/production/etc.
+
+If you don't use Rails, it's still a good idea to move this information to a config file.
+
+The configuration could look like this:
+
+    # wsdl: http://example.org/ws/service?WSDL
+    EXAMPLE_SERVICE_ENDPOINT = {
+      :uri => 'http://example.org/ws/service',
+      :version => 2
+    }
+
+If you use Rails, you will need to load the gem from the `config/environment.rb` file, using:
+
+    config.gem 'troelskn-handsoap', :lib => 'handsoap', :source => "http://gems.github.com"
+
+###Service class
+
+Put your service in a file under `app/models`. You should extend `Handsoap::Service`.
+
+You need to provide the endpoint and the SOAP version (1.1 or 1.2). If in doubt, use version 2.
+
+A service usually has a namespace for describing the message-body ([RPC/Litteral style](http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/#N1011F)). You should set this in the `on_create_document` handler.
+
+A typical service looks like the following:
+
+    # -*- coding: utf-8 -*-
+    require 'handsoap'
+
+    class Example::FooService < Handsoap::Service
+      endpoint EXAMPLE_SERVICE_ENDPOINT
+      on_create_document do |doc|
+        doc.alias 'wsdl', "http://example.org/ws/spec"
+      end
+      # public methods
+      # todo
+
+      private
+      # helpers
+      # todo
+    end
+
+The above would go in the file `app/models/example/foo_service.rb`
+
+###Integration tests
+
+Since you're writing mappings manually, it's a good idea to write tests that verify that the service works. If you use standard Rails with `Test::Unit`, you should put these in an integration-test.
+
+For the sample service above, you would create a file in `test/integration/example/foo_service.rb`, with the following content:
+
+    # -*- coding: utf-8 -*-
+    require 'test_helper'
+
+    # Example::FooService.logger = $stdout
+
+    class Example::FooServiceTest < Test::Unit::TestCase
+      def test_update_icon
+        icon = { :href => 'http://www.example.com/icon.jpg', :type => 'image/jpeg' }
+        result = Example::FooService.update_icon!(icon)
+        assert_equal icon.type, result.type
+      end
+    end
+
+Note the commented-out line. If you set a logger on the service-class, you can see exactly which XML goes forth and back, which is very useful for debugging.
+
+###Methods
+
+You should use Ruby naming-conventions for methods names. If the method has side-effects, you should postfix it with an exclamation.
+Repeat code inside the invoke-block, should be refactored out to *builders*, and the response should be parsed with a *parser*.
+
+    def update_icon!(icon)
+      response = invoke("wsdl:UpdateIcon") do |message|
+        build_icon!(message, icon)
+      end
+      parse_icon(response.document.xpath('//icon').first)
+    end
+
+
+###Helpers
+
+You'll end up with two kinds of helpers; Ruby->XML transformers (aka. *builders*) and XML->Ruby transformers (aka. *parsers*).
+It's recommended that you stick to the following style/naming scheme:
+
+    # icon -> xml
+    def build_icon!(message, icon)
+      message.add "icon" do |i|
+        i.set_attr "href", icon[:href]
+        i.set_attr "type", icon[:type]
+      end
+    end
+
+    # xml -> icon
+    def parse_icon(node)
+      { :href => node['href'], :type => node['type'] }
+    end
+
+or, if you prefer, you can use a class to represent entities:
+
+    # icon -> xml
+    def build_icon!(message, icon)
+      message.add "icon" do |i|
+        i.set_attr "href", icon.href
+        i.set_attr "type", icon.type
+      end
+    end
+
+    # xml -> icon
+    def parse_icon(node)
+      Icon.new :href => node['href'],
+               :type => node['type']
+    end
+
+License
+---
+
+Copyright: [Unwire A/S](http://www.unwire.dk), 2009
+
+License: [Creative Commons Attribution 2.5 Denmark License](http://creativecommons.org/licenses/by/2.5/dk/) 
+
+___
+
+troelskn@gmail.com - April, 2009

data/Rakefile

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "handsoap"
+    gemspec.summary = "Handsoap is a library for creating SOAP clients in Ruby"
+    gemspec.email = "troelskn@gmail.com"
+    gemspec.homepage = "http://github.com/troelskn/handsoap"
+    gemspec.description = gemspec.summary
+    gemspec.authors = ["Troels Knak-Nielsen"]
+    gemspec.add_dependency "nokogiri", ">= 1.2.3"
+    gemspec.add_dependency "curb", ">= 0.3.2"
+#    gemspec.add_dependency "httpclient", ">= 2.1.2"
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 3
+:major: 0
+:minor: 1

data/generators/handsoap/handsoap_generator.rb

@@ -0,0 +1,314 @@
+require 'open-uri'
+require 'uri'
+require 'cgi'
+require 'nokogiri'
+
+# TODO: inline builders, if they are only ever used in one place
+# TODO: http://www.crossedconnections.org/w/?p=51 -- The 'typens' namespace is magical ...
+
+class Builders
+  def initialize(xsd)
+    @xsd = xsd
+    @builders = {}
+  end
+  def add(type)
+    @builders[type] = false unless @builders[type]
+  end
+  def each
+    results = []
+    while builder = @builders.find { |builder,is_rendered| !is_rendered }
+      results << yield(@xsd.get_complex_type(builder[0]))
+      @builders[builder[0]] = true
+    end
+    results.join("")
+  end
+end
+
+class HandsoapGenerator < Rails::Generator::NamedBase
+  attr_reader :wsdl
+  def initialize(runtime_args, runtime_options = {})
+    super
+    # Wsdl argument is required.
+    usage if @args.empty?
+    @wsdl_uri = @args.shift
+  end
+
+  def banner
+		"WARNING: This generator is rather incomplete and buggy. Use at your own risk." +
+			"\n" + "Usage: #{$0} #{spec.name} name URI [options]" +
+      "\n" + "  name  Basename of the service class" +
+      "\n" + "  URI   URI of the WSDL to generate from"
+  end
+
+  def manifest
+    record do |m|
+      @wsdl = Handsoap::Wsdl.new(@wsdl_uri)
+      @wsdl.parse!
+      @xsd = Handsoap::XsdSpider.new(@wsdl_uri)
+      @xsd.process!
+      m.directory "app"
+      m.directory "app/models"
+      @builders = Builders.new(@xsd)
+      m.template "gateway.rbt", "app/models/#{file_name}_service.rb"
+    end
+  end
+
+  def builders
+    @builders
+  end
+
+  def render_build(context_name, message_type, varname = nil, indentation = '    ')
+    if varname.nil?
+      ruby_name = message_type.ruby_name
+    else
+      ruby_name = "#{varname}[:#{message_type.ruby_name}]"
+    end
+    # message_type.namespaces
+    if message_type.attribute?
+      "#{context_name}.set_attr " + '"' + message_type.name + '", ' + ruby_name
+    elsif message_type.boolean?
+      "#{context_name}.add " + '"' + message_type.name + '", bool_to_str(' + ruby_name + ')'
+    elsif message_type.primitive?
+      "#{context_name}.add " + '"' + message_type.name + '", ' + ruby_name
+    elsif message_type.list?
+      list_type = @xsd.get_complex_type(message_type.type)
+      builders.add(list_type.type)
+      # TODO: a naming conflict waiting to happen hereabout
+      # TODO: indentation
+      "#{varname}.each do |#{message_type.ruby_name}|" + "\n" + indentation +
+      "  build_#{list_type.ruby_type}!(#{context_name}, #{message_type.ruby_name})" + "\n" + indentation +
+      "end"
+    else
+      builders.add(message_type.type)
+      "build_#{message_type.ruby_type}!(#{context_name}, " + ruby_name + ")"
+    end
+  end
+
+end
+
+module Handsoap
+
+  class Wsdl
+    attr_reader :uri, :soap_actions, :soap_ports, :target_namespace
+    def initialize(uri)
+      @uri = uri
+    end
+
+    def parse!
+      wsdl = Nokogiri.XML(Kernel.open(@uri).read)
+      @target_namespace = wsdl.namespaces['xmlns:tns'] || wsdl.namespaces['xmlns']
+      @soap_actions = []
+      @soap_ports = []
+      messages = {}
+
+      wsdl.xpath('//wsdl:message').each do |message|
+        message_name = message['name']
+        messages[message_name] = message.xpath('wsdl:part').map { |part| MessageType::Part.new(part['type'] || 'xs:element', part['name']) }
+      end
+
+      wsdl.xpath('//*[name()="soap:operation"]').each do |operation|
+        operation_name = operation.parent['name']
+        operation_spec = wsdl.xpath('//wsdl:operation[@name="' + operation_name + '"]').first
+        raise RuntimeError, "Couldn't find wsdl:operation node for #{operation_name}" if operation_spec.nil?
+        msg_type_in = operation_spec.xpath('./wsdl:input').first["message"]
+        raise RuntimeError, "Couldn't find wsdl:input node for #{operation_name}" if msg_type_in.nil?
+        raise RuntimeError, "Invalid message type #{msg_type_in} for #{operation_name}" if messages[msg_type_in].nil?
+        msg_type_out = operation_spec.xpath('./wsdl:output').first["message"]
+        raise RuntimeError, "Couldn't find wsdl:output node for #{operation_name}" if msg_type_out.nil?
+        raise RuntimeError, "Invalid message type #{msg_type_out} for #{operation_name}" if messages[msg_type_out].nil?
+        @soap_actions << SoapAction.new(operation, messages[msg_type_in], messages[msg_type_out])
+      end
+      raise RuntimeError, "Could not parse WSDL" if soap_actions.empty?
+
+      wsdl.xpath('//wsdl:port', {"xmlns:wsdl" => 'http://schemas.xmlsoap.org/wsdl/'}).each do |port|
+        name = port['name'].underscore
+        location = port.xpath('./*[@location]').first['location']
+        @soap_ports << { :name => name, :soap_name => port['name'], :location => location }
+      end
+    end
+  end
+
+  class SoapAction
+    attr_reader :input_type, :output_type
+    def initialize(xml_node, input_type, output_type)
+      @xml_node = xml_node
+      @input_type = input_type
+      @output_type = output_type
+    end
+    def name
+      @xml_node.parent['name'].underscore
+    end
+    def soap_name
+      @xml_node.parent['name']
+    end
+    def href
+      @xml_node['soapAction']
+    end
+  end
+
+  module MessageType
+
+    # complex-type is a spec (class), not an element ... (object)
+    # <xs:complexType name="User">
+		#   <xs:annotation>
+    #     <xs:documentation>The element specifies a user</xs:documentation>
+    #   </xs:annotation>
+    #   <xs:attribute name="dn" type="xs:string" use="required"/>
+    # </xs:complexType>
+    class ComplexType
+      def initialize(xml_node)
+        @xml_node = xml_node
+      end
+      def type
+        @xml_node['name']
+      end
+      def ruby_type
+        type.gsub(/^.*:/, "").underscore.gsub(/-/, '_')
+      end
+      def elements
+        @xml_node.xpath('./xs:attribute|./xs:all/xs:element|./xs:sequence').map do |node|
+          case
+            when node.node_name == 'attribute'
+            Attribute.new(node['type'], node['name'])
+            when node.node_name == 'element'
+            Element.new(node['type'], node['name'], []) # TODO: elements.elements
+            when node.node_name == 'sequence'
+            choice_node = node.xpath('./xs:choice').first
+            if choice_node
+              # TODO
+              Attribute.new('xs:choice', 'todo')
+            else
+              entity_node = node.xpath('./xs:element').first
+              Sequence.new(entity_node['type'], entity_node['name'])
+            end
+          else
+            puts node
+            raise "Unknown type #{node.node_name}"
+          end
+        end
+      end
+    end
+
+    class Base
+      attr_reader :type, :name
+      def initialize(type, name)
+        raise "'type' can't be nil" if type.nil?
+        raise "'name' can't be nil" if name.nil?
+        @type = type
+        @name = name
+      end
+      def ruby_type
+        type.gsub(/^.*:/, "").underscore.gsub(/-/, '_')
+      end
+      def ruby_name
+        name.underscore.gsub(/-/, '_')
+      end
+      def attribute?
+        false
+      end
+      def primitive?
+        /^xs:/.match type
+      end
+      def boolean?
+        type == "xs:boolean"
+      end
+      def list?
+        false
+      end
+    end
+
+    # Parts are shallow elements
+    # <wsdl:part name="widget-instance-id" type="xs:int" />
+    class Part < Base
+    end
+
+    # <wsdl:part name="widget-instance-id" type="xs:int" />
+    # <xs:element maxOccurs="1" minOccurs="0" name="description" type="xs:string"/>
+    class Element < Base
+      attr_reader :elements
+      def initialize(type, name, elements = [])
+        super(type, name)
+        @elements = elements
+      end
+    end
+
+    # <xs:attribute name="id" type="xs:int" use="required"/>
+    class Attribute < Base
+      def primitive?
+        true
+      end
+      def attribute?
+        true
+      end
+    end
+
+    # <xs:sequence>
+	  #   <xs:element maxOccurs="unbounded" minOccurs="0" name="widget-area" type="WidgetArea"/>
+	  # </xs:sequence>
+    class Sequence < Base
+      def list?
+        true
+      end
+    end
+  end
+end
+
+module Handsoap
+
+  class XsdSpider
+    def initialize(uri)
+      @queue = []
+      @wsdl_uri = uri
+    end
+
+    def results
+      @queue.map { |element| element[:data] }
+    end
+
+    def get_complex_type(name)
+      # TODO namespace
+      short_name = name.gsub(/^.*:/, "")
+      results.each do |data|
+        search = data[:document].xpath('//xs:complexType[@name="' + short_name + '"]')
+        if search.any?
+          return MessageType::ComplexType.new(search.first)
+        end
+      end
+      raise "Didn't find '#{name}' (short name #{short_name})"
+    end
+
+    def process!
+      spider_href(@wsdl_uri, nil)
+      while process_next do end
+    end
+
+    private
+
+    def add_href(href, namespace)
+      unless @queue.find { |element| element[:href] == href }
+        @queue << { :href => href, :namespace => namespace, :state => :new, :data => {} }
+      end
+    end
+
+    def process_next
+      next_element = @queue.find { |element| element[:state] == :new }
+      if next_element
+        next_element[:data] = spider_href(next_element[:href], next_element[:namespace])
+        next_element[:state] = :done
+        return true
+      end
+      return false
+    end
+
+    def spider_href(href, namespace)
+      raise "'href' must be a String" if href.nil?
+      xsd = Nokogiri.XML(Kernel.open(href).read)
+      # <xs:include schemaLocation="...xsd"/>
+      # <xs:import namespace="" schemaLocation="...xsd"/>
+      xsd.xpath('//*[@schemaLocation]').each do |inc|
+        add_href(inc['schemaLocation'], inc['namespace'] || namespace)
+      end
+      { :document => xsd, :namespace => namespace }
+    end
+  end
+end

data/generators/handsoap/templates/gateway.rbt

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+require 'handsoap'
+
+class <%= class_name %>Service < Handsoap::Service
+  endpoint <%= file_name.upcase %>_SERVICE_ENDPOINT
+  on_create_document do |doc|
+    doc.alias 'wsdl', "<%= wsdl.target_namespace %>"
+  end
+<% wsdl.soap_actions.each do |action| %>
+  def <%= action.name %>(<%= action.input_type.map { |message_type| message_type.ruby_name }.join(", ") %>)
+    response = invoke("wsdl:<%= action.soap_name %>") do |context|<% action.input_type.each do |message_type| %>
+      <%= render_build('context', message_type) %><% end %>
+    end
+    response.document.xpath('//*').map { |node| raise "TODO" }
+  end
+<% end %>
+  private
+  # builders
+<% builders.each do |type| %>
+  # <%= type.type %> ruby -> xml
+  def build_<%= type.ruby_type %>!(context, <%= type.ruby_type %>)<% type.elements.each do |element| %>
+    <%= render_build('context', element, type.ruby_type) %><% end %>
+  end
+<% end %>
+  # parsers
+  # TODO
+end

data/lib/handsoap.rb

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+require 'handsoap/xml_mason'
+require 'handsoap/service'
+
+

data/lib/handsoap/service.rb

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+require 'rubygems'
+require 'httpclient'
+require 'nokogiri'
+require 'curb'
+require 'handsoap/xml_mason'
+require 'time'
+
+module Handsoap
+
+  def self.http_driver
+    @http_driver || :curb
+  end
+
+  def self.http_driver=(driver)
+    @http_driver = driver
+  end
+
+  SOAP_NAMESPACE = { 1 => 'http://schemas.xmlsoap.org/soap/envelope/', 2 => 'http://www.w3.org/2001/12/soap-encoding' }
+
+  class Response
+    def initialize(http_body, soap_namespace)
+      @http_body = http_body
+      @soap_namespace = soap_namespace
+      @document = :lazy
+      @fault = :lazy
+    end
+    def document?
+      !! document
+    end
+    def document
+      if @document == :lazy
+        doc = Nokogiri::XML(@http_body)
+        @document = (doc && doc.root && doc.errors.empty?) ? doc : nil
+      end
+      return @document
+    end
+    def fault?
+      !! fault
+    end
+    def fault
+      if @fault == :lazy
+        nodes = document? ? document.xpath('/env:Envelope/env:Body/descendant-or-self::env:Fault', { 'env' => @soap_namespace }) : []
+        @fault = nodes.any? ? Fault.from_xml(nodes.first, :namespace => @soap_namespace) : nil
+      end
+      return @fault
+    end
+  end
+
+  class Fault < Exception
+    attr_reader :code, :reason, :details
+    def initialize(code, reason, details)
+      @code = code
+      @reason = reason
+      @details = details
+    end
+    def to_s
+      "Handsoap::Fault { :code => '#{@code}', :reason => '#{@reason}' }"
+    end
+    def self.from_xml(node, options = { :namespace => nil })
+      if not options[:namespace]
+        raise "Missing option :namespace"
+      end
+      ns = { 'env' => options[:namespace] }
+      fault_code = node.xpath('./env:Code/env:Value/text()', ns).to_s
+      if fault_code == ""
+        fault_code = node.xpath('./faultcode/text()', ns).to_s
+      end
+      reason = node.xpath('./env:Reason/env:Text[1]/text()', ns).to_s
+      if reason == ""
+        reason = node.xpath('./faultstring/text()', ns).to_s
+      end
+      details = node.xpath('./detail/*', ns)
+      self.new(fault_code, reason, details)
+    end
+  end
+
+  class Service
+    @@logger = nil
+    def self.logger=(io)
+      @@logger = io
+    end
+    def self.endpoint(args = {})
+      @protocol_version = args[:version] || raise("Missing option :version")
+      @uri = args[:uri] || raise("Missing option :uri")
+    end
+    def self.envelope_namespace
+      if SOAP_NAMESPACE[@protocol_version].nil?
+        raise "Unknown protocol version '#{@protocol_version.inspect}'"
+      end
+      SOAP_NAMESPACE[@protocol_version]
+    end
+    def self.request_content_type
+      @protocol_version == 1 ? "text/xml" : "application/soap+xml"
+    end
+    def self.map_method(mapping)
+      if @mapping.nil?
+        @mapping = {}
+      end
+      @mapping.merge! mapping
+    end
+    def self.on_create_document(&block)
+      @create_document_callback = block
+    end
+    def self.fire_on_create_document(doc)
+      if @create_document_callback
+        @create_document_callback.call doc
+      end
+    end
+    def self.uri
+      @uri
+    end
+    def self.get_mapping(name)
+      @mapping[name] if @mapping
+    end
+    @@instance = {}
+    def self.instance
+      @@instance[self.to_s] ||= self.new
+    end
+    def self.method_missing(method, *args)
+      if instance.respond_to?(method)
+        instance.__send__ method, *args
+      else
+        super
+      end
+    end
+    def method_missing(method, *args)
+      action = self.class.get_mapping(method)
+      if action
+        invoke(action, *args)
+      else
+        super
+      end
+    end
+		def invoke(action, options = { :soap_action => :auto }, &block)
+			if action
+				if options.kind_of? String
+					options = { :soap_action => options }
+				end
+				if options[:soap_action] == :auto
+					options[:soap_action] = action.gsub(/^.+:/, "")
+				elsif options[:soap_action] == :none
+					options[:soap_action] = nil
+				end
+				doc = make_envelope do |body|
+					body.add action
+				end
+				if block_given?
+					yield doc.find(action)
+				end
+				dispatch(doc, options[:soap_action])
+			end
+		end
+    def on_before_dispatch
+    end
+    def on_fault(fault)
+      raise fault
+    end
+    private
+    # Helper to serialize a node into a ruby string
+    def xml_to_str(node, xquery = nil)
+      begin
+        n = xquery ? node.xpath(xquery, ns).first : node
+        n.serialize('UTF-8')
+      rescue Exception => ex
+        nil
+      end
+    end
+    # Helper to serialize a node into a ruby integer
+    def xml_to_int(node, xquery = nil)
+      begin
+        n = xquery ? node.xpath(xquery, ns).first : node
+        n.to_s.to_i
+      rescue Exception => ex
+        nil
+      end
+    end
+    # Helper to serialize a node into a ruby float
+    def xml_to_float(node, xquery = nil)
+      begin
+        n = xquery ? node.xpath(xquery, ns).first : node
+        n.to_s.to_f
+      rescue Exception => ex
+        nil
+      end
+    end
+    # Helper to serialize a node into a ruby boolean
+    def xml_to_bool(node, xquery = nil)
+      begin
+        n = xquery ? node.xpath(xquery, ns).first : node
+        n.to_s == "true"
+      rescue Exception => ex
+        nil
+      end
+    end
+    # Helper to serialize a node into a ruby Time object
+    def xml_to_date(node, xquery = nil)
+      begin
+        n = xquery ? node.xpath(xquery, ns).first : node
+        Time.iso8601(n.to_s)
+      rescue Exception => ex
+        nil
+      end
+    end
+    def debug(message = nil)
+      if @@logger
+        if message
+          @@logger.puts(message)
+        end
+        if block_given?
+          yield @@logger
+        end
+      end
+    end
+    def dispatch(doc, action)
+      on_before_dispatch()
+      headers = {
+        "Content-Type" => "#{self.class.request_content_type};charset=UTF-8"
+      }
+			headers["SOAPAction"] = action unless action.nil?
+      body = doc.to_s
+      debug do |logger|
+        logger.puts "==============="
+        logger.puts "--- Request ---"
+        logger.puts "URI: %s" % [self.class.uri]
+        logger.puts headers.map { |key,value| key + ": " + value }.join("\n")
+        logger.puts "---"
+        logger.puts body
+      end
+      if Handsoap.http_driver == :curb
+        http_client = Curl::Easy.new(self.class.uri)
+        http_client.headers = headers
+        http_client.http_post body
+        debug do |logger|
+          logger.puts "--- Response ---"
+          logger.puts "HTTP Status: %s" % [http_client.response_code]
+          logger.puts "Content-Type: %s" % [http_client.content_type]
+          logger.puts "---"
+          logger.puts Handsoap.pretty_format_envelope(http_client.body_str)
+        end
+        soap_response = Response.new(http_client.body_str, self.class.envelope_namespace)
+      else
+        response = HTTPClient.new.post(self.class.uri, body, headers)
+        debug do |logger|
+          logger.puts "--- Response ---"
+          logger.puts "HTTP Status: %s" % [response.status]
+          logger.puts "Content-Type: %s" % [response.contenttype]
+          logger.puts "---"
+          logger.puts Handsoap.pretty_format_envelope(response.content)
+        end
+        soap_response = Response.new(response.content, self.class.envelope_namespace)
+      end
+      if soap_response.fault?
+        return self.on_fault(soap_response.fault)
+      end
+      return soap_response
+    end
+    def make_envelope
+      doc = XmlMason::Document.new do |doc|
+        doc.alias 'env', self.class.envelope_namespace
+        doc.add "env:Envelope" do |env|
+          env.add "*:Header"
+          env.add "*:Body"
+        end
+      end
+      self.class.fire_on_create_document doc
+      if block_given?
+        yield doc.find("Body")
+      end
+      return doc
+    end
+  end
+
+  def self.pretty_format_envelope(xml_string)
+    if /^<.*:Envelope/.match(xml_string)
+      begin
+        doc = Nokogiri::XML(xml_string)
+      rescue Exception => ex
+        return "Formatting failed: " + ex.to_s
+      end
+      return doc.to_s
+      # return "\n\e[1;33m" + doc.to_s + "\e[0m"
+    end
+    return xml_string
+  end
+
+end

data/lib/handsoap/xml_mason.rb

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+
+module Handsoap
+
+  module XmlMason
+
+    HTML_ESCAPE = { '&' => '&amp;', '"' => '&quot;', '>' => '&gt;', '<' => '&lt;' }
+
+    def self.html_escape(s)
+      s.to_s.gsub(/[&"><]/) { |special| HTML_ESCAPE[special] }
+    end
+
+    class Node
+      def initialize
+        @namespaces = {}
+      end
+      def add(node_name, value = nil)
+        prefix, name = parse_ns(node_name)
+        node = append_child Element.new(self, prefix, name, value)
+        if block_given?
+          yield node
+        end
+      end
+      def alias(prefix, namespaces)
+        @namespaces[prefix] = namespaces
+      end
+      def parse_ns(name)
+        matches = name.match /^([^:]+):(.*)$/
+        if matches
+          [matches[1] == '*' ? @prefix : matches[1], matches[2]]
+        else
+          [nil, name]
+        end
+      end
+      private :parse_ns
+    end
+
+    class Document < Node
+      def initialize
+        super
+        @document_element = nil
+        if block_given?
+          yield self
+        end
+      end
+      def append_child(node)
+        if not @document_element.nil?
+          raise "There can only be one element at the top level."
+        end
+        @document_element = node
+      end
+      def find(name)
+        @document_element.find(name)
+      end
+      def find_all(name)
+        @document_element.find_all(name)
+      end
+      def get_namespace(prefix)
+        @namespaces[prefix] || raise("No alias registered for prefix '#{prefix}'")
+      end
+      def defines_namespace?(prefix)
+        false
+      end
+      def to_s
+        if @document_element.nil?
+          raise "No document element added."
+        end
+        "<?xml version='1.0' ?>" + "\n" + @document_element.to_s
+      end
+    end
+
+    class TextNode
+      def initialize(text)
+        @text = text
+      end
+      def to_s(indentation = '')
+        XmlMason.html_escape(@text)
+      end
+    end
+
+    class Element < Node
+      def initialize(parent, prefix, node_name, value = nil)
+        super()
+#         if prefix.to_s == ""
+#           raise "missing prefix"
+#         end
+        @parent = parent
+        @prefix = prefix
+        @node_name = node_name
+        @children = []
+        @attributes = {}
+        if not value.nil?
+          set_value value.to_s
+        end
+        if block_given?
+          yield self
+        end
+      end
+      def full_name
+        @prefix.nil? ? @node_name : (@prefix + ":" + @node_name)
+      end
+      def append_child(node)
+        if value_node?
+          raise "Element already has a text value. Can't add nodes"
+        end
+        @children << node
+        return node
+      end
+      def set_value(value)
+        if @children.length > 0
+          raise "Element already has children. Can't set value"
+        end
+        @children = [TextNode.new(value)]
+      end
+      def set_attr(name, value)
+        full_name = parse_ns(name).join(":")
+        @attributes[name] = value
+      end
+      def find(name)
+        if @node_name == name || full_name == name
+          return self
+        end
+        @children.each do |node|
+          if node.respond_to? :find
+            tmp = node.find(name)
+            if tmp
+              return tmp
+            end
+          end
+        end
+        return nil
+      end
+      def find_all(name)
+        result = []
+        if @node_name == name || full_name == name
+          result << self
+        end
+        @children.each do |node|
+          if node.respond_to? :find
+            result = result.concat(node.find_all(name))
+          end
+        end
+        return result
+      end
+      def value_node?
+        @children.length == 1 && @children[0].kind_of?(TextNode)
+      end
+      def get_namespace(prefix)
+        @namespaces[prefix] || @parent.get_namespace(prefix)
+      end
+      def defines_namespace?(prefix)
+        @attributes.keys.include?("xmlns:#{prefix}") || @parent.defines_namespace?(prefix)
+      end
+      def to_s(indentation = '')
+        # todo resolve attribute prefixes aswell
+        if @prefix && (not defines_namespace?(@prefix))
+          set_attr "xmlns:#{@prefix}", get_namespace(@prefix)
+        end
+        name = XmlMason.html_escape(full_name)
+        attr = (@attributes.any? ? (" " + @attributes.map { |key, value| XmlMason.html_escape(key) + '="' + XmlMason.html_escape(value) + '"' }.join(" ")) : "")
+        if @children.any?
+          if value_node?
+            children = @children[0].to_s(indentation + "  ")
+          else
+            children = @children.map { |node| "\n" + node.to_s(indentation + "  ") }.join("") + "\n" + indentation
+          end
+          indentation + "<" + name + attr + ">" + children + "</" + name + ">"
+        else
+          indentation + "<" + name + attr + " />"
+        end
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: digitaria-handsoap
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+platform: ruby
+authors: 
+- Troels Knak-Nielsen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-29 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: curb
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.2
+    version: 
+description: Handsoap is a library for creating SOAP clients in Ruby
+email: troelskn@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- README.markdown
+- Rakefile
+- VERSION.yml
+- generators/handsoap/USAGE
+- generators/handsoap/handsoap_generator.rb
+- generators/handsoap/templates/gateway.rbt
+- lib/handsoap.rb
+- lib/handsoap/service.rb
+- lib/handsoap/xml_mason.rb
+has_rdoc: true
+homepage: http://github.com/troelskn/handsoap
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Handsoap is a library for creating SOAP clients in Ruby
+test_files: []
+