restr 0.3.0 → 0.4.0

data/History.txt

@@ -1,3 +1,17 @@
+== 0.4.0 :: 2008-06-19
+
+* Better recognition of XML content; response MIME types ending in "/xml" and
+  "+xml" are now all parsed as XML (for example: "application/xml", 
+  "image/svg+xml", "text/xml", etc). Note that "application/xhtml+xml" is now
+  considered to be XML content too, even though you may think of it as just
+  "HTML".
+* You can set how long Restr will wait for a request to complete by  setting 
+  Restr.request_timeout = <seconds>. The default timeout is 3  minutes 
+  (180 seconds).
+* The full response body is now included in DEBUG-level log entries. Be careful
+  if you have the logging level set to DEBUG -- your log will now grow very
+  quickly.
+
 == 0.3.0 :: 2008-04-03
 
 * First public release -- moved out from the Reststop library into its own gem.

data/lib/restr.rb

@@ -4,6 +4,7 @@ require 'net/http'
 require 'net/https'
 require 'uri'
 require 'cgi'
+require 'timeout'
 
 begin
   require 'xml_simple'
@@ -44,17 +45,29 @@ end
 # -- see http://xml-simple.rubyforge.org/). Otherwise the response is  
 # returned untouched, as a String.
 #
+#
+# === Authentication
+# 
 # If the remote REST resource requires authentication (Restr only supports
 # HTTP Basic authentication, for now):
 #
 #   Restr.get('http://example.com/kittens/1.xml, {}, 
 #     {:username => 'foo', :password => 'bar'})
 #
+# === Logging
+# 
+# A standard Ruby Logger can be attached to the Restr client like so:
+#
+#   logger = Logger.new('restr.log')
+#   logger.level = Logger::DEBUG
+#   Restr.log = logger
+#
+# Restr will now log its activity to the given Logger. Be careful when using
 class Restr
   
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 3
+    MINOR = 4
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
@@ -62,6 +75,9 @@ class Restr
   
   
   @@log = nil
+  @@request_timeout = 3.minutes
+  
+  cattr_accessor :request_timeout
   
   def self.logger=(logger)
     @@log = logger.dup
@@ -102,7 +118,7 @@ class Restr
       req.basic_auth auth[:username] || auth['username'], auth[:password] || auth['password']
     end
     
-    unless method_mod == 'Get'
+    if params.kind_of?(Hash) && method_mod != 'Get' && method_mod != 'get'
       req.set_form_data(params, '&')
     end
     
@@ -111,26 +127,40 @@ class Restr
  
     client = Net::HTTP.new(uri.host, uri.port)
     client.use_ssl = (uri.scheme == 'https')
-    res = client.start do |http|
-      http.request(req)
+    
+    timeout = Restr.request_timeout
+    client.read_timeout = timeout
+    
+    begin
+      res = client.start do |http|
+        http.request(req)
+      end
+    rescue Timeout::Error
+      res = TimeoutError, "Request timed out after #{timeout} seconds."
     end
     
     case res
     when Net::HTTPSuccess
-      if res.content_type == 'text/xml'
-        @@log.debug("Got XML response.") if @@log
+      if res.content_type =~ /[\/+]xml$/
+        @@log.debug("Got XML response: \n#{res.body}") if @@log
         return XmlSimple.xml_in_string(res.body,
           'forcearray'   => false,
           'keeproot'     => false
         )
       else
-        @@log.debug("Got #{res.content_type.inspect} response.") if @@log
+        @@log.debug("Got #{res.content_type.inspect} response: \n#{res.body}") if @@log
         return res.body
       end
+    when TimeoutError
+      @@log.debug(res) if @@log
+      return XmlSimple.xml_in_string(res,
+          'forcearray'   => false,
+          'keeproot'     => false
+        )
     else
       $LAST_ERROR_BODY = res.body # FIXME: this is dumb... need a better way of reporting errors
       @@log.error("Got error response '#{res.message}(#{res.code})': #{$LAST_ERROR_BODY}") if @@log
-      res.error!      
+      res.error!
     end
   end
   

data/website/index.html

@@ -38,7 +38,17 @@
     <h1>&#x2192; &#8216;restr&#8217;</h1>
 
 
-	<h2>What</h2>
+	<h3>Copyright&#169; 2008 Urbacon Ltd.</h3>
+
+
+	<h2>What is it?</h2>
+
+
+	<p><b>Restr is a very simple client for <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">RESTful</a> web services.</b> 
+It was developed as a lightweight alternative to <a href="http://api.rubyonrails.com/files/vendor/rails/activeresource/README.html">ActiveResource</a>.</p>
+
+
+	<p>For project info and downloads please see the Restr&#8217;s <a href="http://rubyforge.org/projects/restr">RubyForge Page</a></p>
 
 
 	<h2>Installing</h2>
@@ -47,40 +57,57 @@
 	<p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">restr</span></pre></p>
 
 
-	<h2>The basics</h2>
+	<h2>Usage Example</h2>
 
 
-	<h2>Demonstration of usage</h2>
+	<p>Fetch Kitten with id 1 and print out its name and colour:</p>
 
 
-	<h2>Forum</h2>
+	<pre><code>require 'restr'
+kitten = Restr.get('http://example.com/kittens/1.xml')
+puts kitten['name']
+puts kitten['colour']</code></pre>
 
 
-	<p><a href="http://groups.google.com/group/restr">http://groups.google.com/group/restr</a></p>
+	<p>Change the Kitten&#8217;s colour and store the modification:</p>
 
 
-	<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; restr</p>
+	<pre><code>kitten['colour'] = 'black'
+kitten = Restr.put('http://example.com/kittens/1.xml', kitten)</code></pre>
 
 
-	<h2>How to submit patches</h2>
+	<h2>Further Resources</h2>
+
 
+	<ul>
+	<li><a href="http://restr.rubyforge.org/rdoc/" title="RDocs">Full <span class="caps">API</span> Documentation</a></li>
+	</ul>
 
-	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
+
+	<h2>How to submit patches</h2>
 
 
-	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/restr/trunk</code> for anonymous access.</p>
+	<ul>
+	<li>See below for author&#8217;s contact info.</li>
+		<li>The trunk repository is <code>svn://rubyforge.org/var/svn/restr/trunk</code> for anonymous access.</li>
+	</ul>
 
 
 	<h2>License</h2>
 
 
-	<p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
+	<ul>
+	<li><a href="http://www.gnu.org/licenses/lgpl.html">Lesser <span class="caps">GPL</span> Version 3</a></li>
+	</ul>
 
 
 	<h2>Contact</h2>
 
 
-	<p>Comments are welcome. Send an email to <a href="mailto:FIXME"><span class="caps">FIXME</span> full name</a> email via the <a href="http://groups.google.com/group/restr">forum</a></p>
+	<ul>
+	<li><a href="http://rubyforge.org/users/gunark/">Author&#8217;s Rubyforge Page</a></li>
+		<li><a href="http://rubyforge.org/forum/?group_id=5848">Restr RubyForge Forum</a></li>
+	</ul>
     <p class="coda">
       <a href="FIXME email">FIXME full name</a>, 3rd April 2008<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>

data/website/index.txt

@@ -2,38 +2,47 @@ h1. restr
 
 h1. → 'restr'
 
+h3. Copyright (c) 2008 Urbacon Ltd.
 
-h2. What
+h2. What is it?
 
+<b>Restr is a very simple client for "RESTful":http://en.wikipedia.org/wiki/Representational_State_Transfer web services.</b> 
+It was developed as a lightweight alternative to "ActiveResource":http://api.rubyonrails.com/files/vendor/rails/activeresource/README.html.
+
+For project info and downloads please see the Restr's "RubyForge Page":http://rubyforge.org/projects/restr
 
 h2. Installing
 
 <pre syntax="ruby">sudo gem install restr</pre>
 
-h2. The basics
-
-
-h2. Demonstration of usage
+h2. Usage Example
 
+Fetch Kitten with id 1 and print out its name and colour:
 
+  require 'restr'
+  kitten = Restr.get('http://example.com/kittens/1.xml')
+  puts kitten['name']
+  puts kitten['colour']
+  
+Change the Kitten's colour and store the modification:
+  
+  kitten['colour'] = 'black'
+  kitten = Restr.put('http://example.com/kittens/1.xml', kitten)
 
-h2. Forum
+h2. Further Resources
 
-"http://groups.google.com/group/restr":http://groups.google.com/group/restr
-
-TODO - create Google Group - restr
+* "Full API Documentation (RDocs)":http://restr.rubyforge.org/rdoc/
 
 h2. How to submit patches
 
-Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
-
-The trunk repository is <code>svn://rubyforge.org/var/svn/restr/trunk</code> for anonymous access.
+* See below for author's contact info.
+* The trunk repository is <code>svn://rubyforge.org/var/svn/restr/trunk</code> for anonymous access.
 
 h2. License
 
-This code is free to use under the terms of the MIT license. 
+* "Lesser GPL Version 3":http://www.gnu.org/licenses/lgpl.html
 
 h2. Contact
 
-Comments are welcome. Send an email to "FIXME full name":mailto:FIXME email via the "forum":http://groups.google.com/group/restr
-
+* "Author's Rubyforge Page":http://rubyforge.org/users/gunark/
+* "Restr RubyForge Forum":http://rubyforge.org/forum/?group_id=5848

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: restr
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Matt Zukowski
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-04-03 00:00:00 -04:00
+date: 2008-06-19 00:00:00 -04:00
 default_executable: 
 dependencies: []