socialcast-rapuncel 0.0.7.RC1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://www.rubygems.org'
+gemspec
+gem 'rake', :require => false
+

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    rapuncel (0.0.6.RC3)
+      activesupport (>= 3.0.0)
+      nokogiri
+
+GEM
+  remote: http://www.rubygems.org/
+  specs:
+    activesupport (3.1.3)
+      multi_json (~> 1.0)
+    diff-lcs (1.1.2)
+    multi_json (1.0.4)
+    nokogiri (1.5.0)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rapuncel!
+  rspec (>= 2.6.0)

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Kayoom GmbH
+
+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,209 @@
+# Rapuncel - Simple XML-RPC Client
+[![Build Status](https://secure.travis-ci.org/cice/rapuncel.png)](http://travis-ci.org/cice/rapuncel)
+
+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.
+
+## I need your help
+I currently have exactly 1 application for Rapuncel, and that's [Kangaroo](https://github.com/kayoom/kangaroo), i.e.
+the OpenERP XMLRPC service, where it works absolutely fine. To improve Rapuncel i need your experience with
+other services and their quirks. Just open a feature request, file a bug report, send me a message.
+  
+## 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**
+Password for HTTP Authentication  
+_default_: _empty_
+* **headers**
+Hash to set additional HTTP headers for the request, e.g. to send an X-ApiKey header for authentication  
+_default_: `{}`
+* **ssl**
+Flag wether to use SSL  
+_default_: `false`
+* **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
+* **serialization**
+Use your own (extended) (De)Serializers. See Custom Serialization  
+_default_: `Rapuncel::XmlRpc`
+
+### 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 / Double
+* BigDecimal (treated like Float, unless you set `double_as_bigdecimal` to true)
+* Time, Time-like objects
+* Base64
+
+* Symbols are converted to Strings
+* All Hashs have symbol keys
+* All other objects are transformed into a Hash ('struct' in XMLRPC-speak) containing their instance variables as key-value-pairs.
+
+## Base64
+If you want a string to be encoded as Base64 in your RPC call, just mark it:
+
+    proxy.some_method "my base64 encoded string".as_base64
+    
+Return values that arrive Base64 encoded, are instances of Rapuncel::Base64String,
+which is a subclass of String, and therefore can be used as such, but allows you to differentiate
+Base64 return values from normal String return values.
+
+## Supported methods
+You can use most methods via
+
+    proxy.methodname 'a', 1, [:a, :b], :a => :d
+
+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 a parsed result
+
+## Deserialization options
+
+At the moment there are 2 options, to be set quite ugly as class attributes on Rapuncel::XmlRpc::Deserializer,
+which will definitely change.
+
+1. **double\_as\_bigdecimal**
+Deserialize all `<double>` tags as BigDecimal.
+2. **hash\_keys\_as\_string**
+Don't use Symbols as keys for deserialized `<struct>`, but Strings.
+
+## Custom Serialization
+
+    module MySpecialSerialization
+      class Serializer < Rapuncel::XmlRpc::Serializer
+      end
+      class Deserializer < Rapuncel::XmlRpc::Deserializer
+      end
+    end
+    
+    client = Rapuncel::Client.new :serialization => MySpecialSerialization
+    # or :serialization => 'MySpecialSerialization'
+
+## Todo ?
+
+* RDoc
+* Extensive functional tests
+* HTTP-Proxy support
+* Async requests
+* XMLRPC Extensions (pluggable support)
+  * Apache vendor extensions
+* How do i test SSL?
+
+## 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.
+
+## Changelog
+
+* **0.0.5**
+  * Refactored serialization, preparation for pluggable extensions
+  * Deserialization option "double\_as\_bigdecimal"
+  * Deserialization option "hash\_keys\_as\_string"
+  * base64 support
+  * Object#to\_xmlrpc now should expect a XmlRpc::Serializer instance, 
+    not a Builder (you can access the Builder directly via XmlRpc::Serializer#builder)
+
+## Open Source
+
+### License
+
+Copyright (c) 2011 Kayoom GmbH
+
+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 '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
+
+begin
+  require 'rspec/core/rake_task'
+  desc 'Run RSpec suite.'
+  RSpec::Core::RakeTask.new('spec')
+rescue LoadError
+  puts "RSpec is not available. In order to run specs, you must: gem install rspec"
+end
+
+desc 'Default: run unit tests.'
+task :default => :spec

data/lib/rapuncel/adapters/curb_adapter.rb

@@ -0,0 +1,43 @@
+require 'curb'
+
+module Rapuncel
+  module Adapters
+    module CurbAdapter
+      # Small response wrapper
+      class HttpResponse
+        def initialize body, code
+          @body, @code = body, code
+        end
+
+        def success?
+          !(@code =~ /^2/)
+        end
+
+        def body
+          @body
+        end
+
+        def code
+          @code
+        end
+      end
+
+      # Dispatch a XMLRPC via HTTP and return a response object.
+      def send_method_call str
+        @curb ||= Curl::Easy.new "#{connection.protocol}://#{connection.host}:#{connection.port}#{connection.path}"
+
+        if connection.auth?
+          @curb.username = connection.user
+          @curb.password = connection.password
+          @curb.enable_cookies = true
+          @curb.cookiejar = connection.cookie_file_path
+        end
+        @curb.post_body = str
+        @curb.headers = @curb.headers.merge connection.headers
+        @curb.perform
+
+        HttpResponse.new @curb.body_str, @curb.response_code
+      end
+    end
+  end
+end

data/lib/rapuncel/adapters/net_http_adapter.rb

@@ -0,0 +1,60 @@
+require 'net/http'
+require 'net/https'
+require 'cookiejar'
+require 'json'
+
+module Rapuncel
+  module Adapters
+    module NetHttpAdapter
+      # Small response wrapper
+      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
+
+      # Dispatch a XMLRPC via HTTP and return a response object.
+      def send_method_call str
+        cookie_jar = if File.exists?(connection.cookie_file_path)
+          File.open(connection.cookie_file_path, 'r') do |file|
+            contents = file.read
+            if contents.empty? 
+              CookieJar::Jar.new 
+            else
+              CookieJar::Jar.json_create(JSON.parse(contents))
+            end
+          end
+        else
+          CookieJar::Jar.new
+        end
+        cookie_header = {}
+        cookie_header['Cookie'] = cookie_jar.get_cookie_header("#{connection.ssl? ? 'https' : 'http'}://#{connection.host}/")
+        
+        request = Net::HTTP::Post.new(connection.path, connection.headers.merge(cookie_header))
+        request.basic_auth connection.user, connection.password if connection.auth?
+        request.body= str
+        
+        http = Net::HTTP.new(connection.host, connection.port)
+        http.use_ssl = connection.ssl?
+        http.set_debug_output(STDOUT)
+        response = http.request(request)
+        cookie_jar.set_cookie("#{connection.ssl? ? 'https' : 'http'}://#{connection.host}/", response.header['Set-Cookie'])
+        
+        File.open(connection.cookie_file_path, 'w'){ |file| file.write(cookie_jar.to_json) }
+        HttpResponse.new response
+      end
+    end
+  end
+end

data/lib/rapuncel/base_64_string.rb

@@ -0,0 +1,36 @@
+if RUBY_VERSION =~ /^1\.8/
+  require 'base64'
+end
+
+class String
+  def as_base64
+    Rapuncel::Base64String.new self
+  end
+end
+
+module Rapuncel
+  class Base64String < String
+
+    if RUBY_VERSION =~ /^1\.9/
+
+      def base64_encoded
+        [self].pack 'm'
+      end
+    
+      def self.decode_base64 string
+        new string.unpack('m')[0]
+      end
+      
+    else
+
+      def base64_encoded
+        Base64.encode64 self
+      end
+    
+      def self.decode_base64 string
+        new Base64.decode64 string
+      end
+
+    end
+  end
+end

data/lib/rapuncel/client/logging.rb

@@ -0,0 +1,83 @@
+require 'logger'
+
+module Rapuncel
+  module Client::Logging
+    attr_accessor :logger
+    
+    def log_level
+      @logger.try :level
+    end
+    
+    def log_level= log_level
+      @logger && @logger.level = log_level
+    end
+    
+    def logger= logger
+      @logger = case logger
+      when Logger
+        logger
+      when IO
+        Logger.new logger
+      when String, Symbol
+        Logger.new ActiveSupport::Inflector.constantize(logger.to_s.upcase)
+      else
+        Logger.new STDOUT
+      end
+    end
+    
+    protected
+    def initialize_logging logger, log_level
+      self.logger = logger
+      if log_level
+        self.log_level = log_level
+      end
+      
+      @logger.info { with_log_prefix "Initialized." }
+      @logger.debug { with_log_prefix "Using (De)Serializer: #{serialization.to_s}" }
+    end
+    
+    def _call name, *args
+      if logger.debug?
+        logger.debug { with_log_prefix "Calling RPC Method \"#{name}\" with #{args.map(&:inspect).join(', ')}" }
+      else
+        logger.info { with_log_prefix "Calling RPC Method \"#{name}\" with #{args.length} arguments." }
+      end
+      
+      super
+    end
+    
+    def send_method_call xml
+      logger.debug { with_log_prefix "Sending XML:\n #{xml}" }
+      
+      super
+    end
+    
+    def execute request
+      super.tap do |response|
+        case
+        when response.success?
+          logger.debug { "Received XML-Response: \n #{response.body}" }
+        when response.fault?
+          level = raise_on_fault ? Logger::ERROR : Logger::WARN
+          logger.add(level) { "Received XML-Fault: \n #{response.body}" }
+        when response.error?
+          level = raise_on_error ? Logger::ERROR : Logger::WARN
+          logger.add(level) { "HTTP Error: #{response.status}\n #{response.body}" }
+        end
+      end
+    end
+    
+    private
+    def log_host_config
+      "#{connection.host}:#{connection.port}#{connection.path}"
+    end
+    
+    def with_log_prefix message
+      "#{log_prefix} #{message}"
+    end
+    
+    def log_prefix
+      @log_prefix ||= "[XML-RPC@#{log_host_config}]"
+    end
+  end
+end

data/lib/rapuncel/client.rb

@@ -0,0 +1,117 @@
+begin
+  require 'rapuncel/adapters/curb_adapter'
+rescue LoadError
+  require 'rapuncel/adapters/net_http_adapter'
+end
+require 'rapuncel/connection'
+require 'rapuncel/xml_rpc/serializer'
+require 'rapuncel/xml_rpc/deserializer'
+require 'active_support/core_ext/hash/except'
+require 'active_support/inflector/methods'
+require 'active_support/deprecation'
+
+module Rapuncel
+  class Client
+    autoload :Logging, 'rapuncel/client/logging'
+    
+    attr_accessor :connection, :raise_on_fault, :raise_on_error
+    
+    if defined?(Adapters::CurbAdapter)
+      include Adapters::CurbAdapter
+    else
+      include Adapters::NetHttpAdapter
+    end
+
+    def initialize configuration = {}
+      @connection = Connection.new configuration.except(:raise_on, :serialization)
+      @serialization = configuration[:serialization]
+      
+      @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
+      
+      if logger = configuration[:logger]
+        extend Logging
+        initialize_logging logger, configuration[:log_level]
+      end
+    end
+
+    def proxy_for interface = nil
+      if interface.nil?
+        @default_proxy ||= Proxy.new self, nil
+      else
+        @proxies ||= Hash.new do |hash, key|
+          hash[key] = Proxy.new self, key
+        end
+        
+        @proxies[interface.to_s]
+      end
+    end
+
+    def proxy
+      proxy_for nil
+    end
+
+    # Dispatch a method call and return the response as Rapuncel::Response object.
+    def call name, *args
+      ActiveSupport::Deprecation.warn "Using #call is deprecated, please use #call_to_ruby instead.", caller
+      _call name, *args
+    end
+
+    # Dispatch a method call and return the response as parsed ruby.
+    def call_to_ruby name, *args
+      response = _call name, *args
+
+      raise_on_fault && response.fault? && raise_fault(response)
+      raise_on_error && response.error? && raise_error(response)
+
+      response.to_ruby
+    end
+
+    protected
+    def _call name, *args
+      execute Request.new(name, *args)
+    end
+    
+    def execute request
+      xml = serializer[request]
+
+      Response.new send_method_call(xml), deserializer
+    end
+    
+    def serialization
+      case @serialization
+      when Module
+        @serialization
+      when String, Symbol
+        ActiveSupport::Inflector.constantize(@serialization.to_s)
+      else
+        XmlRpc
+      end
+    end
+    
+    def serializer
+      @serializer ||= serialization.const_get 'Serializer'
+    end
+    
+    def deserializer
+      @deserializer ||= serialization.const_get 'Deserializer'
+    end
+    
+    private
+    def raise_fault response
+      raise(Response::Fault, response.fault[:faultCode], response.fault[:faultString].split("\n"))
+    end
+    
+    def raise_error response
+      raise(Response::Error, "HTTP Error: #{response.error.inspect}")
+    end
+  end
+end

data/lib/rapuncel/connection.rb

@@ -0,0 +1,65 @@
+module Rapuncel
+  class Connection
+    attr_accessor :host, :port, :path, :ssl, :user, :password, :cookie_file_path
+    alias_method :ssl?, :ssl
+
+    def initialize configuration = {}
+      load_configuration configuration
+    end
+
+    def url
+      "#{protocol}://#{host}:#{port}#{path}"
+    end
+    
+    def host= value
+      @host = value.to_s.sub /^http(s)?\:\/\//, ''
+      
+      if $1 == 's'
+        @ssl = true
+      end
+      
+      @host
+    end
+    
+    def path= value
+      unless value =~ /^\//
+        value = "/" + value
+      end
+      
+      @path = value
+    end
+    
+    def headers= headers
+      @headers = {
+        'User-Agent' => 'Rapuncel, Ruby XMLRPC Client'
+      }.merge headers.stringify_keys
+    end
+
+    def headers
+      @headers.merge 'Accept' => 'text/xml', 'content-type' => 'text/xml'
+    end
+    
+    def protocol
+      ssl? ? 'https' : 'http'
+    end
+    alias_method :scheme, :protocol
+    
+    def auth?
+      !!user && !!password
+    end
+    
+    protected
+    def load_configuration configuration
+      configuration = configuration.symbolize_keys
+      
+      self.ssl      = !!configuration[:ssl]
+      self.host     = configuration[:host]    || 'localhost'
+      self.port     = configuration[:port]    || '8080'
+      self.path     = configuration[:path]    || '/'
+      self.headers  = configuration[:headers] || {}
+      self.user     = configuration[:user]
+      self.password = configuration[:password]
+      self.cookie_file_path = configuration[:cookie_file_path]
+    end
+  end
+end