rapuncel 0.0.1.alpha

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 ['Marian Theisen', 'Michael Eickenberg']
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# Rapuncel - Simple XML-RPC Client
+
+Rapuncel ([wikipedia](http://en.wikipedia.org/wiki/Rapunzel)) is a simple and lightweight, but fast XML-RPC client library for ruby.
+It's based on Nokogiri for XML parsing and thus provides a major performance improvement for large XML responses.
+
+## Installation
+
+### Rails
+Add this to your Gemfile:
+
+    gem 'rapuncel'
+
+Run
+
+    bundle install
+
+and you're good to go.
+
+### Other Ruby / IRB
+Install it as gem:
+
+    gem install rapuncel
+
+Require **rubygems** and **rapuncel**
+
+    require 'rubygems'
+    require 'rapuncel'
+
+## Usage
+
+### Initialize client
+Usage is pretty straightforward, Rapuncel provides a method proxy to send calls to your XMLRPC service like you would to a normal ruby
+object.
+First you have to create a client with the connection details, e.g.
+
+    client = Rapuncel::Client.new :host => 'localhost', :port => 8080, :path => '/xmlrpc'
+
+Available options are:
+
+* **host**
+hostname or ip-address,
+_default_: localhost
+* **port**
+port where your XMLRPC service is listening,
+_default_: 8080
+* **path**
+path to the service,
+_default_: /
+* **user**
+Username for HTTP Authentication
+_default_: _empty_
+* **password**
+Username for HTTP Authentication
+_default_: _empty_
+* **auth\_method**
+HTTP Auth method
+_default_: basic **IF** user or password is set
+* **api\_key**
+If set, sends all request with a X-ApiKey: _api\_key_ header
+* **api\_key\_header**
+Allows you to modify the header key for API-Key auth
+_default_: X-ApiKey
+* **raise_on**
+Lets you define the behavior on errors or faults, if set to _:fault_, _:error_ or _:both_,
+an Exception will be raised if something goes wrong
+
+### Get a proxy object and ...
+A proxy object receives ruby method calls, redirects them to your XMLRPC service and returns the response as ruby objects!
+
+    proxy = client.proxy
+
+    # suppose your XMLRPC service has a method exposed 'concat_string(string1, string2)'
+    proxy.concat_string "foo", "bar"
+    -> "foobar"
+
+    # if you need to access specific interfaces on your service, e.g. 'string.concat(string1, string2)'
+    proxy = client.proxy_for 'string'
+    proxy.concat 'foo', 'bar'
+    -> 'foobar'
+
+## Supported objects
+Rapuncel supports natively following object-types (and all their subclasses):
+
+* Integer
+* String
+* Array
+* Hash
+* TrueClass, FalseClass
+* Float
+* BigDecimal (treated like Float)
+* Time, Time-like objects
+
+* Symbols are converted to Strings
+
+* All other objects are transformed into a Hash ('struct' in XMLRPC-speak) containing their instance variables as key-value-pairs.
+
+### Can i customize this behavior for my objects?
+Yes you can, and it's dead simple, just override _to\_xml\_rpc_ with following signature (this is taken from Symbol#to\_xml\_rpc):
+
+    def to_xml_rpc(builder = Rapuncel.get_builder)
+      self.to_s.to_xml_rpc(builder)
+    end
+
+Of course you don't have to delegate to #to\_s, you just can use the Builder object directly
+
+    def to_xml_rpc(builder = Rapuncel.get_builder)
+      builder.string(self.to_s)
+    end
+
+## Supported methods
+You can use most methods via
+
+    proxy.methodname *args
+
+However methods starting with \_\_, or ending with a bang \! or a question mark ? are not supported. To call those methods you can always
+use
+
+    proxy.call! 'methodname', *args
+
+or via
+
+    client.call_to_ruby 'methodname', *args
+
+note
+
+    client.call 'methodname', *args
+
+will return a Rapuncel::Response object, use _call\_to\_ruby_ to get standard ruby objects
+
+## Todo ?
+
+* RDoc
+* Extensive functional tests
+* Async requests
+* Base64 support (or rather a consistent concept for Base64)
+* XMLRPC Extensions (pluggable support)
+
+## What happens if something goes wrong?
+### HTTP Errors / XMLRPC Faults
+See Usage -> configuration -> raise\_on switch
+### Malformed XML/XMLRPC
+Rapuncel will most likely fail hard.
+
+## Open Source
+
+### License
+
+Copyright (c) 2010 ['Marian Theisen', 'Michael Eickenberg']
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+### Contribution
+
+Pull requests are very welcome!

data/Rakefile

@@ -0,0 +1,24 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run Rapuncel Testsuite.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+#TODO: sdoc
+desc 'Generate Rapuncel rdoc.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rapuncel'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/rapuncel.rb

@@ -0,0 +1,25 @@
+
+
+require 'active_support/core_ext/hash/keys'
+
+require 'nokogiri'
+
+require 'rapuncel/base'
+require 'rapuncel/request'
+require 'rapuncel/response'
+require 'rapuncel/client'
+require 'rapuncel/proxy'
+
+# Ruby Core extensions:
+require 'rapuncel/core_ext/object'
+require 'rapuncel/core_ext/string'
+require 'rapuncel/core_ext/symbol'
+require 'rapuncel/core_ext/integer'
+require 'rapuncel/core_ext/big_decimal'
+require 'rapuncel/core_ext/float'
+require 'rapuncel/core_ext/hash'
+require 'rapuncel/core_ext/array'
+require 'rapuncel/core_ext/boolean'
+require 'rapuncel/core_ext/nil'
+
+require 'rapuncel/core_ext/time'

data/lib/rapuncel/adapters/net_http_adapter.rb

@@ -0,0 +1,34 @@
+require 'net/http'
+require 'active_support/memoizable'
+
+module Rapuncel
+  module Adapters
+    module NetHttpAdapter
+      extend ActiveSupport::Memoizable
+
+      class HttpResponse
+        def initialize response
+          @response = response
+        end
+
+        def success?
+          @response.is_a? Net::HTTPOK
+        end
+
+        def body
+          @response.body
+        end
+
+        def code
+          @response.code
+        end
+      end
+
+      def send_method_call str
+        req = Net::HTTP.new connection.host, connection.port
+
+        HttpResponse.new req.post(connection.path, str, connection.headers.stringify_keys)
+      end
+    end
+  end
+end

data/lib/rapuncel/base.rb

@@ -0,0 +1,7 @@
+module Rapuncel
+  BUILDER_OPTIONS = {:encoding => 'UTF-8'}
+
+  def self.get_builder options = {}
+    Nokogiri::XML::Builder.new options
+  end
+end

data/lib/rapuncel/client.rb

@@ -0,0 +1,54 @@
+require 'rapuncel/adapters/net_http_adapter'
+require 'rapuncel/connection'
+require 'active_support/core_ext/hash/except'
+
+module Rapuncel
+  class Client
+    attr_accessor :connection, :raise_on_fault, :raise_on_error
+
+    include Adapters::NetHttpAdapter
+
+    def proxy_for interface
+      Proxy.new self, interface
+    end
+
+    def proxy
+      proxy_for nil
+    end
+
+    def initialize configuration = {}
+      @connection = Connection.build configuration.except(:raise_on)
+
+      @raise_on_fault, @raise_on_error = case configuration[:raise_on]
+      when :fault
+        [true, false]
+      when :error
+        [false, true]
+      when :both
+        [true, true]
+      else
+        [false, false]
+      end
+    end
+
+    def call name, *args
+      execute Request.new(name, *args)
+    end
+
+    def call_to_ruby name, *args
+      response = call name, *args
+
+      raise_on_fault && response.fault? && raise(response.fault)
+      raise_on_error && response.error? && raise(response.error)
+
+      response.to_ruby
+    end
+
+    protected
+    def execute request
+      xml = request.to_xml_rpc
+
+      Response.new send_method_call(xml)
+    end
+  end
+end

data/lib/rapuncel/connection.rb

@@ -0,0 +1,75 @@
+module Rapuncel
+  class Connection
+    def self.build configuration = {}
+      configuration = configuration.symbolize_keys
+
+      case
+      when configuration[:user], configuration[:auth_method], configuration[:password]
+        AuthConnection.new configuration
+      when configuration[:api_key_header], configuration[:api_key]
+        ApiKeyAuthConnection.new configuration
+      else
+        new configuration
+      end
+    end
+
+    attr_accessor :host, :port, :path, :ssl, :headers
+    alias_method :ssl?, :ssl
+
+    def initialize configuration = {}
+
+      @host     = configuration[:host]    || 'localhost'
+      @port     = configuration[:port]    || '8080'
+      @path     = configuration[:path]    || '/'
+      @headers  = configuration[:headers] || {}
+
+
+      if ssl = configuration[:ssl]
+        @ssl = true
+        #TODO
+      end
+    end
+
+    def url
+      "http://#{host}:#{port}#{path}"
+    end
+
+    def headers
+      @headers.merge  :Accept => 'text/xml', :'content-type' => 'text/xml'
+    end
+
+    def http_auth? ; false ; end
+    def api_auth? ; false ; end
+  end
+
+  class AuthConnection < Connection
+    attr_accessor :auth_method, :user, :password
+
+    def initialize configuration = {}
+      super
+
+      @auth_method  = auth_method               || 'basic'
+      @user         = user                      || ''
+      @password     = configuration[:password]  || ''
+    end
+
+    def http_auth? ; true ; end
+  end
+
+  class ApiKeyAuthConnection < Connection
+    attr_accessor :api_key_header, :api_key
+
+    def initialize configuration = {}
+      super
+
+      @api_key_header = configuration[:api_key_header] || "X-ApiKey"
+      @api_key        = configuration[:api_key]        || '' #DISCUSS: raise error ?
+    end
+
+    def headers
+      super.merge api_key_header => api_key
+    end
+
+    def api_auth? ; true ; end
+  end
+end

data/lib/rapuncel/core_ext/array.rb

@@ -0,0 +1,23 @@
+class Array
+  def to_xml_rpc b = Rapuncel.get_builder
+    b.array do |b|
+      b.data do |b|
+        each do |array_entry|
+          b.value do |b|
+            array_entry.to_xml_rpc b
+          end
+        end
+      end
+    end
+
+    b.to_xml
+  end
+
+  def self.from_xml_rpc xml_node
+    values = xml_node.first_element_child.element_children
+
+    values.map do |value|
+      Object.from_xml_rpc value.first_element_child
+    end
+  end
+end