james-rc-rest 2.2.1

data/History.txt

@@ -0,0 +1,30 @@
+= 2.2.1
+
+* Turn IOError into RCRest::CommunicationError for #post and #post_multipart.
+
+= 2.2.0
+
+* Moved to seattlerb rubyforge project
+* Moved to p4
+* Wrap communication errors in RCRest::CommunicationError
+
+= 2.1.1
+
+* Fix dependency on ZenTest for testing
+
+= 2.1.0
+
+* Don't split strings into extra params pairs on newlines
+* Added RCRest#post_multipart and RCRest#make_multipart
+* Fixed various query parameter incompatiblities
+
+= 2.0.0
+
+* Added +method+ parameter to RCRest#make_url to add path components
+  to a generic endpoint
+* Added RCRest#post
+
+= 1.0.0
+
+* Birthday!
+

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright 2006 Eric Hodel, The Robot Co-op.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the names of the authors nor the names of their contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Manifest.txt

@@ -0,0 +1,9 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/rc_rest.rb
+lib/rc_rest/net_http_stub.rb
+lib/rc_rest/uri_stub.rb
+test/test_rc_rest.rb

data/README.txt

@@ -0,0 +1,32 @@
+= rc-rest
+
+Rubyforge Project:
+
+http://rubyforge.org/projects/rctools/
+
+Documentation:
+
+http://dev.robotcoop.com/Libraries/rc-rest/
+
+== About
+
+This is an abstract class for creating wrappers for REST web service APIs.
+
+== Installing rc-rest
+
+Just install the gem:
+
+  $ sudo gem install rc-rest
+
+== Using rc-rest
+
+rc-rest is used by gems such as yahoo-search, google-geocode and geocoder-us.
+If you'd like to write bindings a web service using rc-rest see RCRest, its
+tests or the above-mentioned gems for examples.
+
+== Upgrading from 1.x
+
+RCRest#get and RCRest#make_url now accept a method argument as the
+first parameter.  To use 2.x, pass the last component of the path to
+RCRest#get or RCRest#make_url.
+

data/Rakefile

@@ -0,0 +1,18 @@
+require 'hoe'
+require './lib/rc_rest'
+
+Hoe.new 'rc-rest', RCRest::VERSION do |p|
+  p.summary = 'Robot Co-op REST web services base class'
+  p.description = 'This library makes it easy to implement REST-like web services APIs.'
+  p.author = 'Eric Hodel'
+  p.email = 'drbrain@segment7.net'
+  p.url = "http://seattlerb.rubyforge.org/rc-rest"
+  p.rubyforge_name = 'seattlerb'
+
+  p.changes = File.read('History.txt').scan(/\A(=.*?)^=/m).first.first
+
+  p.extra_deps << ['ZenTest', '>= 3.4.2']
+end
+
+# vim: syntax=Ruby
+

data/lib/rc_rest.rb

@@ -0,0 +1,279 @@
+require 'net/http'
+require 'open-uri'
+require 'rexml/document'
+
+##
+# Abstract class for implementing REST APIs.
+#
+# === Example
+#
+# The following methods must be implemented in sublcasses:
+#
+# +initialize+:: Sets @url to the service enpoint.
+# +check_error+:: Checks for errors in the server response.
+# +parse_response+:: Extracts information from the server response.
+#
+# If you have extra URL paramaters (application id, output type) or need to
+# perform URL customization, override +make_url+ and +make_multipart+.
+#
+#   class FakeService < RCRest
+#   
+#     class Error < RCRest::Error; end
+#   
+#     def initialize(appid)
+#       @appid = appid
+#       @url = URI.parse 'http://example.com/api/'
+#     end
+#   
+#     def check_error(xml)
+#       raise Error, xml.elements['error'].text if xml.elements['error']
+#     end
+#   
+#     def make_url(method, params)
+#       params[:appid] = @appid
+#       super method, params
+#     end
+#   
+#     def parse_response(xml)
+#       return xml
+#     end
+#   
+#     def test(query)
+#       get :test, :q => query
+#     end
+#   
+#   end
+
+class RCRest
+
+  ##
+  # You are using this version of RCRest
+
+  VERSION = '2.2.1'
+
+  ##
+  # Abstract Error class.
+
+  class Error < RuntimeError; end
+
+  ##
+  # Error raised when communicating with the server
+
+  class CommunicationError < Error
+
+    ##
+    # The original exception
+
+    attr_accessor :original_exception
+
+    ##
+    # Creates a new CommunicationError with +message+ and +original_exception+
+
+    def initialize(original_exception)
+      @original_exception = original_exception
+      message = "Communication error: #{original_exception.message}(#{original_exception.class})"
+      super message
+    end
+
+  end
+
+  ##
+  # Web services initializer.
+  #
+  # Concrete web services implementations must set the +url+ instance
+  # variable which must be a URI.
+
+  def initialize
+    raise NotImplementedError, 'need to implement #intialize and set @url'
+  end
+
+  ##
+  # Must extract and raise an error from +xml+, an REXML::Document, if any.
+  # Must return if no error could be found.
+
+  def check_error(xml)
+    raise NotImplementedError
+  end
+
+  def expand_params(params) # :nodoc:
+    expanded_params = []
+
+    params.each do |k,v|
+      if v.respond_to? :each and not String === v then
+        v.each { |v| expanded_params << [k, v] }
+      else
+        expanded_params << [k, v]
+      end
+    end
+
+    expanded_params.sort_by { |k,v| [k.to_s, v.to_s] }
+  end
+
+  ##
+  # Performs a GET request for method +method+ with +params+.  Calls
+  # #parse_response on the concrete class with an REXML::Document instance and
+  # returns its result.
+
+  def get(method, params = {})
+    url = make_url method, params
+
+    url.open do |xml|
+      res = REXML::Document.new xml.read
+
+      check_error res
+
+      return parse_response(res)
+    end
+  rescue IOError, SystemCallError, SocketError, Timeout::Error,
+         REXML::ParseException => e
+    raise CommunicationError.new(e)
+  rescue OpenURI::HTTPError => e
+    begin
+      xml = REXML::Document.new e.io.read
+      check_error xml
+    rescue REXML::ParseException => e
+    end
+    new_e = CommunicationError.new e
+    new_e.message << "\n\nunhandled error:\n#{xml.to_s}"
+    raise new_e
+  end
+
+  ##
+  # Creates a URI for method +method+ and a Hash of parameters +params+.
+  # Override this then call super if you need to add extra params like an
+  # application id, output type, etc.
+  #
+  # If the value of a parameter responds to #each, make_url creates a
+  # key-value pair per value in the param.
+  #
+  # Examples:
+  #
+  # If the URL base is:
+  #
+  #   http://example.com/api/
+  #
+  # then:
+  #
+  #   make_url nil, :a => '1 2', :b => [4, 3]
+  #
+  # creates the URL:
+  #
+  #   http://example.com/api/?a=1%202&b=3&b=4
+  #
+  # and
+  #
+  #   make_url :method, :a => '1'
+  #
+  # creates the URL:
+  #
+  #   http://example.com/api/method?a=1
+
+  def make_url(method, params = nil)
+    escaped_params = expand_params(params).map do |k,v|
+      k = URI.escape(k.to_s).gsub(';', '%3B').gsub('+', '%2B').gsub('&', '%26')
+      v = URI.escape(v.to_s).gsub(';', '%3B').gsub('+', '%2B').gsub('&', '%26')
+      "#{k}=#{v}"
+    end
+
+    query = escaped_params.join '&'
+
+    url = @url + "./#{method}"
+    url.query = query
+    return url
+  end
+
+  ##
+  # Creates a multipart form post for the Hash of parameters +params+.
+  # Override this then call super if you need to add extra params like an
+  # application id, output type, etc.
+  #
+  # #make_multipart handles arguments similarly to #make_url.
+
+  def make_multipart(params)
+    boundary = (0...8).map { rand(255).to_s 16 }.join '_'
+    data = expand_params(params).map do |key, value|
+      [ "--#{boundary}",
+        "Content-Disposition: form-data; name=\"#{key}\"",
+        nil,
+        value]
+    end
+
+    data << "--#{boundary}--"
+    return [boundary, data.join("\r\n")]
+  end
+
+  ##
+  # Must parse results from +xml+, an REXML::Document, into something sensible
+  # for the API.
+
+  def parse_response(xml)
+    raise NotImplementedError
+  end
+
+  ##
+  # Performs a POST request for method +method+ with +params+.  Calls
+  # #parse_response on the concrete class with an REXML::Document instance and
+  # returns its result.
+
+  def post(method, params = {})
+    url = make_url method, params
+    query = url.query
+    url.query = nil
+
+    req = Net::HTTP::Post.new url.path
+    req.body = query
+    req.content_type = 'application/x-www-form-urlencoded'
+
+    res = Net::HTTP.start url.host, url.port do |http|
+      http.request req
+    end
+
+    xml = REXML::Document.new res.body
+
+    check_error xml
+
+    parse_response xml
+  rescue SystemCallError, SocketError, Timeout::Error, IOError,
+         REXML::ParseException => e
+    raise CommunicationError.new(e)
+  rescue Net::HTTPError => e
+    xml = REXML::Document.new e.res.body
+    check_error xml
+    raise CommunicationError.new(e)
+  end
+
+  ##
+  # Performs a POST request for method +method+ with +params+, submitting a
+  # multipart form.  Calls #parse_response on the concrete class with an
+  # REXML::Document instance and returns its result.
+
+  def post_multipart(method, params = {})
+    url = make_url method, {}
+    url.query = nil
+
+    boundary, data = make_multipart params
+
+    req = Net::HTTP::Post.new url.path
+    req.content_type = "multipart/form-data; boundary=#{boundary}"
+    req.body = data
+
+    res = Net::HTTP.start url.host, url.port do |http|
+      http.request req
+    end
+
+    xml = REXML::Document.new res.body
+
+    check_error xml
+
+    parse_response xml
+  rescue SystemCallError, SocketError, Timeout::Error, IOError,
+         REXML::ParseException => e
+    raise CommunicationError.new(e)
+  rescue Net::HTTPError => e
+    xml = REXML::Document.new e.res.body
+    check_error xml
+    raise CommunicationError.new(e)
+  end
+
+end
+

data/lib/rc_rest/net_http_stub.rb

@@ -0,0 +1,65 @@
+require 'net/http'
+
+class Net::HTTPResponse
+
+  ##
+  # Setter for body content
+
+  attr_accessor :body
+
+end
+
+class Net::HTTP
+
+  @params = nil
+  @paths = nil
+  @responses = nil
+
+  class << self
+
+    ##
+    # Records submitted POST params
+
+    attr_accessor :params
+
+    ##
+    # Records POST paths
+
+    attr_accessor :paths
+
+    ##
+    # Holds POST body responses
+
+    attr_accessor :responses
+
+    remove_method :start
+
+  end
+
+  ##
+  # Override Net::HTTP::start to not connect
+
+  def self.start(host, port)
+    yield Net::HTTP.new(host)
+  end
+
+  remove_method :request
+
+  ##
+  # Override Net::HTTP#request to fake its results
+
+  def request(req)
+    self.class.paths << req.path
+    self.class.params << req.body
+    response = self.class.responses.shift
+    if response.respond_to? :call then
+      response.call req
+    else
+      res = Net::HTTPResponse.new '1.0', 200, 'OK'
+      res.body = response
+      res
+    end
+  end
+
+end
+

data/lib/rc_rest/uri_stub.rb

@@ -0,0 +1,56 @@
+require 'open-uri'
+
+module URI # :nodoc:
+end
+
+##
+# This stub overrides OpenURI's open method to allow programs that use OpenURI
+# to be easily tested.
+#
+# == Usage
+#
+#   require 'rc_rest/uri_stub'
+#   
+#   class TestMyClass < Test::Unit::TestCase
+#     
+#     def setup
+#       URI::HTTP.responses = []
+#       URI::HTTP.uris = []
+#       
+#       @obj = MyClass.new
+#     end
+#     
+#     def test_my_method
+#       URI::HTTP.responses << 'some text open would ordinarily return'
+#       
+#       result = @obj.my_method
+#       
+#       assert_equal :something_meaninfgul, result
+#       
+#       assert_equal true, URI::HTTP.responses.empty?
+#       assert_equal 1, URI::HTTP.uris.length
+#       assert_equal 'http://example.com/path', URI::HTTP.uris.first
+#     end
+#     
+#  end
+
+class URI::HTTP # :nodoc:
+
+  class << self
+    attr_accessor :responses, :uris
+  end
+
+  alias original_open open
+
+  def open
+    self.class.uris << self.to_s
+    response = self.class.responses.shift
+    if response.respond_to? :call then
+      response.call
+    else
+      yield StringIO.new(response)
+    end
+  end
+
+end
+

data/test/test_rc_rest.rb

@@ -0,0 +1,268 @@
+require 'test/unit'
+require 'rubygems'
+require 'test/zentest_assertions'
+require 'rc_rest/uri_stub'
+require 'rc_rest/net_http_stub'
+require 'rc_rest'
+
+class FakeService < RCRest
+
+  class Error < RCRest::Error; end
+
+  def initialize
+    @url = URI.parse 'http://example.com/test'
+  end
+
+  def check_error(xml)
+    raise Error, xml.elements['error'].text if xml.elements['error']
+  end
+
+  def do_get
+    get :method
+  end
+
+  def do_post
+    post :method, :param => 'value'
+  end
+
+  def do_post_multipart
+    post_multipart :method, :param => 'value'
+  end
+
+  def parse_response(xml)
+    return xml
+  end
+
+end
+
+class TestFakeService < Test::Unit::TestCase
+
+  def setup
+    URI::HTTP.responses = []
+    URI::HTTP.uris = []
+
+    Net::HTTP.params = []
+    Net::HTTP.paths = []
+    Net::HTTP.responses = []
+
+    @fs = FakeService.new
+
+    srand 0
+  end
+
+  def test_check_error
+    xml = REXML::Document.new '<error>you broked it</error>'
+    @fs.check_error xml
+
+  rescue FakeService::Error => e
+    assert_equal 'you broked it', e.message
+
+  else
+    flunk 'expected an error'
+  end
+
+  def test_do_get
+    xml = '<result>stuff</result>'
+    URI::HTTP.responses << xml
+
+    result = @fs.do_get
+
+    assert_equal xml, result.to_s
+    assert_equal 'http://example.com/method?', URI::HTTP.uris.first
+  end
+
+  def test_do_get_bad_xml
+    xml = '<result>stuff</result><extra/>'
+    URI::HTTP.responses << xml
+
+    assert_raise RCRest::CommunicationError do @fs.do_get end
+  end
+
+  def test_do_get_error_400
+    URI::HTTP.responses << proc do
+      xml = '<error>you did the bad thing</error>'
+      raise OpenURI::HTTPError.new('400 Bad Request', StringIO.new(xml))
+    end
+
+    assert_raise FakeService::Error do @fs.do_get end
+  end
+
+  def test_do_get_error_400_bad_xml
+    URI::HTTP.responses << proc do
+      xml = '<error>you did the bad thing</error><extra/>'
+      raise OpenURI::HTTPError.new('400 Bad Request', StringIO.new(xml))
+    end
+
+    assert_raise RCRest::CommunicationError do @fs.do_get end
+  end
+
+  def test_do_get_error_unhandled
+    URI::HTTP.responses << proc do
+      xml = '<other_error>you did the bad thing</other_error>'
+      raise OpenURI::HTTPError.new('500 Internal Server Error', StringIO.new(xml))
+    end
+
+    e = assert_raise RCRest::CommunicationError do @fs.do_get end
+
+    expected = <<-EOF.strip
+Communication error: 500 Internal Server Error(OpenURI::HTTPError)
+
+unhandled error:
+<other_error>you did the bad thing</other_error>
+    EOF
+
+    assert_equal expected, e.message
+  end
+
+  def test_do_get_eof_error
+    URI::HTTP.responses << proc do
+      xml = '<error>you did the bad thing</error>'
+      raise EOFError, 'end of file reached'
+    end
+
+    assert_raise RCRest::CommunicationError do @fs.do_get end
+  end
+
+  def test_do_post
+    xml = '<result>stuff</result>'
+    Net::HTTP.responses << xml
+
+    result = @fs.do_post
+
+    assert_equal xml, result.to_s
+
+    assert_equal 1, Net::HTTP.params.length
+    assert_equal 1, Net::HTTP.paths.length
+    assert_empty Net::HTTP.responses
+
+    assert_equal 'param=value', Net::HTTP.params.first
+    assert_equal '/method', Net::HTTP.paths.first
+  end
+
+  def test_do_post_bad_xml
+    xml = '<result>stuff</result><extra/>'
+    Net::HTTP.responses << xml
+
+    assert_raise RCRest::CommunicationError do @fs.do_post end
+  end
+
+  def test_do_post_eof_error
+    Net::HTTP.responses << proc do
+      raise IOError, 'end of file reached'
+    end
+
+    assert_raise RCRest::CommunicationError do @fs.do_post end
+  end
+
+  def test_do_post_multipart
+    xml = '<result>stuff</result>'
+    Net::HTTP.responses << xml
+
+    result = @fs.do_post_multipart
+
+    assert_equal xml, result.to_s
+
+    assert_equal 1, Net::HTTP.params.length
+    assert_equal 1, Net::HTTP.paths.length
+    assert_empty Net::HTTP.responses
+
+    expected = <<-EOF.strip
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="param"\r
+\r
+value\r
+--ac_2f_75_c0_43_fb_c3_67--
+    EOF
+
+    assert_equal expected, Net::HTTP.params.first
+    assert_equal '/method', Net::HTTP.paths.first
+  end
+
+  def test_do_post_multipart_eof_error
+    Net::HTTP.responses << proc do
+      raise EOFError, 'end of file reached'
+    end
+
+    assert_raise RCRest::CommunicationError do @fs.do_post_multipart end
+  end
+
+  def test_do_post_multipart_bad_xml
+    xml = '<result>stuff</result><extra/>'
+    Net::HTTP.responses << xml
+
+    assert_raise RCRest::CommunicationError do @fs.do_post_multipart end
+  end
+
+end
+
+class TestRCRest < Test::Unit::TestCase
+
+  def test_initialize
+    e = assert_raise NotImplementedError do
+      RCRest.new
+    end
+
+    assert_equal 'need to implement #intialize and set @url', e.message
+  end
+
+  def test_check_error
+    r = RCRest.allocate
+    assert_raise NotImplementedError do r.check_error nil end
+  end
+
+  def test_make_multipart
+    srand 0
+
+    r = RCRest.allocate
+    boundary, data = r.make_multipart :a => 'b c', :x => 'y z',
+                                      :array => ['v2', 'v1'],
+                                      :newlines => "a\nb"
+
+    assert_equal 'ac_2f_75_c0_43_fb_c3_67', boundary
+
+    expected = <<-EOF.strip
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="a"\r
+\r
+b c\r
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="array"\r
+\r
+v1\r
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="array"\r
+\r
+v2\r
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="newlines"\r
+\r
+a
+b\r
+--ac_2f_75_c0_43_fb_c3_67\r
+Content-Disposition: form-data; name="x"\r
+\r
+y z\r
+--ac_2f_75_c0_43_fb_c3_67--
+    EOF
+
+    assert_equal expected, data
+  end
+
+  def test_make_url
+    r = RCRest.allocate
+    r.instance_variable_set :@url, URI.parse('http://example.com/')
+
+    url = r.make_url :method, :a => 'b c', :x => 'y z', :array => ['v2', 'v1'],
+                              :newlines => "a\nb", :funky => 'a;b+c&d'
+
+    assert_equal 'http://example.com/method?a=b%20c&array=v1&array=v2&funky=a%3Bb%2Bc%26d&newlines=a%0Ab&x=y%20z',
+                 url.to_s
+  end
+
+  def test_parse_response
+    r = RCRest.allocate
+    assert_raise NotImplementedError do r.parse_response nil end
+  end
+
+end
+

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: james-rc-rest
+version: !ruby/object:Gem::Version 
+  version: 2.2.1
+platform: ruby
+authors: 
+- Eric Hodel
+- James Darling
+autorequire: 
+bindir: bin
+cert_chain: 
+date: 2007-01-31 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ZenTest
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.4.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.7
+    version: 
+description: JAMES' VERSION OF This library makes it easy to implement REST-like web services APIs.
+email: drbrain@segment7.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- History.txt
+- LICENSE.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/rc_rest.rb
+- lib/rc_rest/net_http_stub.rb
+- lib/rc_rest/uri_stub.rb
+- test/test_rc_rest.rb
+has_rdoc: true
+homepage: http://seattlerb.rubyforge.org/rc-rest
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.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: 1
+summary: James' mashup of rc-rest
+test_files: 
+- test/test_rc_rest.rb