Rapuncel - Simple XML-RPC Client
Rapuncel (wikipedia) 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, 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.
Add this to your Gemfile:
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 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:
hostname or ip-address,
port where your XMLRPC service is listening,
path to the service,
Username for HTTP Authentication
Password for HTTP Authentication
Hash to set additional HTTP headers for the request, e.g. to send an X-ApiKey header for authentication
Flag wether to use SSL
Lets you define the behavior on errors or faults, if set to
an Exception will be raised if something goes wrong
Use your own (extended) (De)Serializers. See Custom Serialization
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'
Rapuncel supports natively following object-types (and all their subclasses):
Float / Double
BigDecimal (treated like Float, unless you set
Time, Time-like objects
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.
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.
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
client.call_to_ruby 'methodname', *args
client.call 'methodname', *args
will return a Rapuncel::Response object, use call_to_ruby to get a parsed result
At the moment there are 2 options, to be set quite ugly as class attributes on Rapuncel::XmlRpc::Deserializer, which will definitely change.
<double>tags as BigDecimal.
Don't use Symbols as keys for deserialized
<struct>, but Strings.
module MySpecialSerialization class Serializer < Rapuncel::XmlRpc::Serializer end class Deserializer < Rapuncel::XmlRpc::Deserializer end end client = Rapuncel::Client.new :serialization => MySpecialSerialization # or :serialization => 'MySpecialSerialization'
- 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
Rapuncel will most likely fail hard.
- 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)
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.
Pull requests are very welcome!