crohr-restfully 0.1.1 → 0.2.1

data/README.rdoc

@@ -1,8 +1,76 @@
 = restfully
 
-An attempt at dynamically providing "clever" wrappers on top of RESTful APIs that follow the HATEOAS principle. For it to work, the API must follow certain conventions (to be explained later).
+An attempt at dynamically providing "clever" wrappers on top of RESTful APIs that follow the principle of Hyperlinks As The Engine Of Application State (HATEOAS). For it to work, the API must follow certain conventions (to be explained later).
 
-Alpha work, will probably only work against my API of reference :-)
+Alpha work.
+
+== Installation
+  $ gem install restfully
+
+== Usage
+=== Command line
+  $ resfully api_base_uri relative_root_uri [-u username] [-p password]
+  
+e.g., for the Grid5000 API:
+  $ restfully https://api.grid5000.fr/sid /grid5000 -u username -p password
+
+If the connection was successful, you should get a prompt. Call the +root+ function to see what are the available resources. <tt>@property</tt> means that you can call the +property+ method on the object. Other properties are available via the <tt>[]</tt> function.
+e.g.:
+  irb(main):005:0> root
+  => #<Restfully::Resource:0x90bdd4
+       ------------ META ------------
+       @uri: "/grid5000"
+       @uid: "grid5000"
+       @type: "grid"
+       @environments: Restfully::Collection
+       @sites: Restfully::Collection
+       @version: Restfully::Resource
+       @versions: Restfully::Collection
+       ------------ PROPERTIES ------------
+       "version" => "ee1f8111c8835496a9e4a6f7c9491c0238ee9827">
+   irb(main):006:0> root.uri
+   => "/grid5000"
+   irb(main):007:0> root.sites
+   => #<Restfully::Collection:0x8faaf2
+        ------------ META ------------
+        @uri: "/grid5000/sites"
+        ------------ PROPERTIES ------------
+        "lille" => Restfully::Resource
+        "grenoble" => Restfully::Resource
+        "toulouse" => Restfully::Resource
+        "sophia" => Restfully::Resource
+        "rennes" => Restfully::Resource
+        "lyon" => Restfully::Resource
+        "nancy" => Restfully::Resource
+        "bordeaux" => Restfully::Resource
+        "orsay" => Restfully::Resource>
+   irb(main):008:0> root['version']
+   => "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
+   irb(main):009:0> root.version
+   => #<Restfully::Resource:0x8facf0
+        ------------ META ------------
+        @uri: "/grid5000/versions/ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
+        @uid: "ee1f8111c8835496a9e4a6f7c9491c0238ee9827"
+        @type: "version"
+        @parent: Restfully::Resource
+        ------------ PROPERTIES ------------
+        "author" => "Cyril Constantin <>"
+        "date" => "Fri, 11 Sep 2009 14:32:48 GMT"
+        "message" => "[environments] update of environments on sites">
+
+You may also prefer to use a configuration file to avoid entering the command line options:
+  $ echo '
+  base_uri: https://api.grid5000.fr/sid
+  relative_root_uri: /grid5000
+  username: MYLOGIN
+  password: MYPASSWORD
+  ' > ~/somewhere/api.grid5000.fr.yml
+
+And then:
+  $ restfully -c ~/somewhere/api.grid5000.fr.yml
+
+=== As a library
+See the +examples+ directory for examples.
 
 == Note on Patches/Pull Requests
  

data/Rakefile

@@ -10,8 +10,8 @@ begin
     gem.email = "cyril.rohr@gmail.com"
     gem.homepage = "http://github.com/crohr/restfully"
     gem.authors = ["Cyril Rohr"]
-    gem.add_dependency "rest-client"    
-    
+    gem.add_dependency "rest-client", '>= 1.0'
+    gem.rubyforge_project = 'restfully'
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
 
@@ -31,16 +31,45 @@ Spec::Rake::SpecTask.new(:rcov) do |spec|
   spec.rcov = true
 end
 
+# These are new tasks
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
 
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
 
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
 
-task :default => :spec
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/the-perfect-gem/"
+        local_dir = 'rdoc'
 
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  task :yardoc do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
   end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
 end
+
+Jeweler::RubyforgeTasks.new do |rubyforge|
+  rubyforge.doc_task = "rdoc"
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'restfully'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO.rdoc

@@ -0,0 +1,3 @@
+* Detects methods allowed on a resource using the Allow HTTP header, and generate corresponding wrappers.
+* On a 406, detects accepted content based on a (custom) HTTP header, and retry (if possible) with another Accept header for which a parser is available.
+* Investigate the possibility of using a :include => {} when loading resources or collection so that Restfully prefetches the included associations (using threads or events).

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.1

data/bin/restfully

@@ -10,7 +10,7 @@ require 'pp'
 
 @options = {}
 option_parser = OptionParser.new do |opts|
-  opts.banner = "Usage: restfully base_url [root_uri] [options]"
+  opts.banner = "Usage: restfully base_uri [root_path] [options]"
 
   opts.on("-u=", "--username=", "Sets the username") do |u|
     @options['username'] = u
@@ -37,17 +37,17 @@ end
 
 option_parser.parse!
 
-@base_url = ARGV.shift
-@root_uri = ARGV.shift || "/"
+@base_uri = ARGV.shift
+@root_path = ARGV.shift || "/"
 
 if (config_filename = @options.delete('configuration_file')) && File.exists?(File.expand_path(config_filename))
   config = YAML.load_file(File.expand_path(config_filename))
-  @base_url = config.delete('base_url') || @base_url
-  @root_uri = config.delete('root_uri') || @root_uri
+  @base_uri = config.delete('base_uri') || @base_uri
+  @root_path = config.delete('root_path') || @root_path
   @options.merge!(config)
 end
 
-unless @base_url
+unless @base_uri
   $stderr.puts option_parser.help
   exit(-1)
 else
@@ -63,10 +63,10 @@ else
   end
 
   def session
-    @session ||= Restfully::Session.new(@base_url, @options.merge('root' => @root_uri, 'logger' => @logger))
+    @session ||= Restfully::Session.new(@base_uri, @options.merge('root_path' => @root_path, 'logger' => @logger))
   end
   def root 
-    @root ||= Restfully::Resource.new(session.root, session).load
+    @root ||= Restfully::Resource.new(session.root_path, session).load
   end
   
   root # preloads

data/examples/grid5000.rb

@@ -1,4 +1,5 @@
 require 'rubygems'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'pp'
 
 require File.dirname(__FILE__)+'/../lib/restfully'
@@ -9,7 +10,7 @@ logger.level = Logger::INFO
 # Restfully.adapter = Restfully::HTTP::RestClientAdapter
 # Restfully.adapter = Patron::Session
 RestClient.log = 'stdout'
-Restfully::Session.new('https://localhost:3443/sid', 'root' => '/grid5000', 'logger' => logger) do |grid, session|
+Restfully::Session.new('https://localhost:3443/sid', 'root_path' => '/grid5000', 'logger' => logger) do |grid, session|
   grid_stats = {'hardware' => {}, 'system' => {}}
   grid.sites.each do |site_uid, site|
     site_stats = site.status.inject({'hardware' => {}, 'system' => {}}) {|accu, (node_uid, node_status)|

data/lib/restfully/collection.rb

@@ -6,10 +6,11 @@ module Restfully
     attr_reader :state, :raw, :uri, :session, :title
     
     def initialize(uri, session, options = {})
+      options = options.symbolize_keys
       @uri = uri
-      @title = options['title']
+      @title = options[:title]
       @session = session
-      @raw = options['raw']
+      @raw = options[:raw]
       @state = :unloaded
       @items = {}
       super(@items)
@@ -19,25 +20,20 @@ module Restfully
     
     def load(options = {})
       options = options.symbolize_keys
-      force_reload = options.delete(:reload) || false
-      path = uri
-      if options.has_key?(:query)
-        path, query_string = uri.split("?")
-        query_string ||= ""
-        query_string.concat(options.delete(:query).to_params)
-        path = "#{path}?#{query_string}"
-        force_reload = true
-      end      
-      if loaded? && force_reload == false
+      force_reload = !!options.delete(:reload) || options.has_key?(:query)
+      if loaded? && !force_reload
         self
-      else
-        @raw = session.get(path, options) if raw.nil? || force_reload
+      else  
         @items.clear
+        if raw.nil? || force_reload
+          response = session.get(uri, options)
+          @raw = response.body
+        end
         raw.each do |key, value|
           next if key == 'links'
           self_link = (value['links'] || []).map{|link| Link.new(link)}.detect{|link| link.self?}
           if self_link && self_link.valid?
-            @items.store(key, Resource.new(self_link.href, session, 'raw' => value).load)
+            @items.store(key, Resource.new(self_link.href, session, :raw => value).load)
           else
             session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
           end
@@ -47,7 +43,7 @@ module Restfully
       end
     end
     
-    def inspect(options = {:space => "     "})
+    def inspect(options = {:space => "\t"})
       output = "#<#{self.class}:0x#{self.object_id.to_s(16)}"
       if loaded?
         output += "\n#{options[:space]}------------ META ------------"

data/lib/restfully/error.rb

@@ -0,0 +1,4 @@
+
+module Restfully  
+  class Error < StandardError; end
+end

data/lib/restfully/http/adapters/abstract_adapter.rb

@@ -0,0 +1,30 @@
+module Restfully
+  module HTTP
+    module Adapters
+      
+      class AbstractAdapter
+        attr_reader :logger, :options
+        def initialize(base_uri, options = {})
+          @options = options.symbolize_keys
+          @logger = @options.delete(:logger) || Restfully::NullLogger.new
+          @base_uri = base_uri
+          logger.debug "base_uri = #{base_uri.inspect}, options = #{options.inspect}."
+        end
+        
+        def get(request)
+          raise NotImplementedError, "GET is not supported by your adapter."
+        end
+        def post(request)
+          raise NotImplementedError, "POST is not supported by your adapter."
+        end
+        def put(request)
+          raise NotImplementedError, "PUT is not supported by your adapter."
+        end
+        def delete(request)
+          raise NotImplementedError, "DELETEis not supported by your adapter."
+        end
+      end
+      
+    end
+  end
+end

data/lib/restfully/http/adapters/patron_adapter.rb

@@ -0,0 +1,16 @@
+require 'restfully/http/adapters/abstract_adapter'
+require 'patron'
+
+module Restfully
+  module HTTP
+    module Adapters
+      class PatronAdapter < AbstractAdapter
+        
+        def initialize(base_url, options = {})
+          super(base_url, options)
+        end
+        
+      end
+    end
+  end
+end

data/lib/restfully/http/adapters/rest_client_adapter.rb

@@ -0,0 +1,31 @@
+require 'restfully/http/adapters/abstract_adapter'
+require 'restclient'
+
+module Restfully
+  module HTTP
+    module Adapters
+      class RestClientAdapter < AbstractAdapter
+        def initialize(base_uri, options = {})
+          super(base_uri, options)
+          @options[:user] = @options.delete(:username)
+        end
+        def get(request)
+          begin
+            resource = RestClient::Resource.new(request.uri.to_s, @options)
+            response = resource.get(request.headers)
+            headers = response.headers
+            body = response.to_s
+            headers.delete(:status)
+            status = response.code
+          rescue RestClient::ExceptionWithResponse => e
+            body = e.http_body
+            headers = e.response.to_hash
+            status = e.http_code
+          end
+          Response.new(status, headers, body)
+        end
+      end
+    
+    end
+  end
+end

data/lib/restfully/http/error.rb

@@ -0,0 +1,20 @@
+module Restfully
+  module HTTP
+    class Error < Restfully::Error
+      attr_reader :response
+      def initialize(response)
+        @response = response
+        if response.body.kind_of?(Hash)
+          message = "#{response.status} #{response.body['title']}. #{response.body['message']}"
+        else
+          message = response.body
+        end
+        super(message)
+      end
+    end
+    class ClientError < Restfully::HTTP::Error; end
+    class ServerError < Restfully::HTTP::Error; end
+  end
+end
+      
+      

data/lib/restfully/http/headers.rb

@@ -0,0 +1,20 @@
+module Restfully
+  module HTTP
+    module Headers
+      def sanitize_http_headers(headers = {})
+        sanitized_headers = {}
+        headers.each do |key, value|
+          sanitized_key = key.to_s.downcase.gsub(/[_-]/, ' ').split(' ').map{|word| word.capitalize}.join("-")
+          sanitized_value = case value
+          when Array 
+            value.join(", ")
+          else 
+            value
+          end
+          sanitized_headers[sanitized_key] = sanitized_value
+        end
+        sanitized_headers
+      end
+    end
+  end
+end

data/lib/restfully/http/request.rb

@@ -0,0 +1,24 @@
+require 'uri'
+module Restfully
+  module HTTP
+    class Request
+      include Headers
+      attr_reader :headers, :body, :uri
+      attr_accessor :retries
+      def initialize(url, options = {})
+        options = options.symbolize_keys
+        @uri = url.kind_of?(URI) ? url : URI.parse(url)
+        @headers = sanitize_http_headers(options.delete(:headers) || {})
+        if query = options.delete(:query)
+          @uri.query = [@uri.query, query.to_params].compact.join("&")
+        end
+        @body = body
+        @retries = 0
+      end
+      
+      def add_headers(headers = {})
+        @headers.merge!(sanitize_http_headers(headers || {}))
+      end
+    end
+  end
+end

data/lib/restfully/http/response.rb

@@ -0,0 +1,19 @@
+module Restfully
+  module HTTP
+    # Container for an HTTP Response. Has <tt>status</tt>, <tt>headers</tt> and <tt>body</tt> properties.
+    # The body is automatically parsed into a ruby object based on the response's <tt>Content-Type</tt> header.
+    class Response
+      include Headers, Restfully::Parsing
+      attr_reader :status, :headers
+      def initialize(status, headers, body)
+        @status = status.to_i
+        @headers = sanitize_http_headers(headers)
+        @body = (body.nil? || body.empty?) ? nil : body.to_s
+      end
+      
+      def body
+        @unserialized_body ||= unserialize(@body, :content_type => @headers['Content-Type']) unless @body.nil?
+      end
+    end
+  end
+end

data/lib/restfully/http.rb

@@ -0,0 +1,9 @@
+require 'restfully/http/headers'
+require 'restfully/http/error'
+require 'restfully/http/request'
+require 'restfully/http/response'
+require 'restfully/http/adapters/abstract_adapter'
+module Restfully
+  module HTTP
+  end
+end

data/lib/restfully/parsing.rb

@@ -2,23 +2,23 @@ require 'json'
 
 module Restfully
   
-  class ParserNotFound < RestfullyError; end
-  
   module Parsing
-    def parse(object, options = {})
+  
+    class ParserNotFound < Restfully::Error; end
+    def unserialize(object, options = {})
       content_type = options[:content_type]
-      content_type ||= object.headers[:content_type] if object.respond_to?(:headers)
+      content_type ||= object.headers['Content-Type'] if object.respond_to?(:headers)
       case content_type
       when /^application\/json/i
         JSON.parse(object)
       else
-        raise ParserNotFound, [object, content_type]
+        raise ParserNotFound.new("Content-Type '#{content_type}' is not supported. Cannot parse the given object.")
       end
     end
   
-    def dump(object, options = {})
+    def serialize(object, options = {})
       content_type = options[:content_type]
-      content_type ||= object.headers[:content_type] if object.respond_to?(:headers)
+      content_type ||= object.headers['Content-Type'] if object.respond_to?(:headers)
       case content_type
       when /^application\/json/i
         JSON.dump(object)

data/lib/restfully/resource.rb

@@ -10,9 +10,10 @@ module Restfully
     attr_reader :uri, :session, :state, :raw, :uid, :associations, :type
 
     def initialize(uri, session, options = {})
+      options = options.symbolize_keys
       @uri = uri
       @session = session
-      @raw = options['raw']
+      @raw = options[:raw]
       @state = :unloaded
       @attributes = {}
       super(@attributes)
@@ -32,21 +33,16 @@ module Restfully
   
     def load(options = {})
       options = options.symbolize_keys
-      force_reload = options.delete(:reload) || false
-      path = uri
-      if options.has_key?(:query)
-        path, query_string = uri.split("?")
-        query_string ||= ""
-        query_string.concat(options.delete(:query).to_params)
-        path = "#{path}?#{query_string}"
-        force_reload = true
-      end
-      if loaded? && force_reload == false
+      force_reload = !!options.delete(:reload) || options.has_key?(:query)
+      if loaded? && !force_reload
         self
-      else
-        @raw = session.get(path, options) if raw.nil? || force_reload
+      else  
         @associations.clear
         @attributes.clear
+        if raw.nil? || force_reload
+          response = session.get(uri, options) 
+          @raw = response.body
+        end
         (raw['links'] || []).each{|link| define_link(Link.new(link))}
         raw.each do |key, value|
           case key
@@ -73,7 +69,7 @@ module Restfully
       @associations.has_key?(method.to_s) || super(method, *args)
     end
     
-    def inspect(options = {:space => "     "})
+    def inspect(options = {:space => "\t"})
       output = "#<#{self.class}:0x#{self.object_id.to_s(16)}"
       if loaded?
         output += "\n#{options[:space]}------------ META ------------"
@@ -102,14 +98,15 @@ module Restfully
         when 'collection'
           raw_included = link.resolved? ? raw[link.title] : nil
           @associations[link.title] = Collection.new(link.href, session, 
-            'raw' => raw_included,
-            'title' => link.title)
+            :raw => raw_included,
+            :title => link.title)
         when 'member'
           raw_included = link.resolved? ? raw[link.title] : nil
           @associations[link.title] = Resource.new(link.href, session, 
-            'raw' => raw_included)
+            :title => link.title,
+            :raw => raw_included)
         when 'self'
-          @uri = link.href
+          # we do nothing
         end
       else 
         session.logger.warn link.errors.join("\n")

data/lib/restfully/session.rb

@@ -1,11 +1,8 @@
 require 'uri'
 require 'logger'
-require 'restclient'
 require 'restfully/parsing'
 
 module Restfully
-  class Error < StandardError; end
-  class HTTPError < Error; end
   class NullLogger
     def method_missing(method, *args)
       nil
@@ -13,49 +10,52 @@ module Restfully
   end
   class Session
     include Parsing
-    attr_reader :base_url, :logger, :connection, :root
+    attr_reader :base_uri, :root_path, :logger, :connection, :root, :default_headers
     
     # TODO: use CacheableResource
-    def initialize(base_url, options = {})
-      options = options.stringify_keys
-      @base_url = base_url
-      @root = options['root'] || '/'
-      @logger = options['logger'] || NullLogger.new 
-      @username = options['username']
-      @password = options['password']
-      # TODO: generalize
-      # @connection = Patron::Session.new
-      # @connection.timeout = 10
-      # @connection.base_url = base_url
-      # @connection.headers['User-Agent'] = 'restfully'
-      # @connection.insecure = true
-      # @connection.username = @user
-      # @connection.password = @password      
-      @connection = RestClient::Resource.new(base_url || '', :user => @username, :password => @password)
-      yield Resource.new(root, self).load, self if block_given?
+    def initialize(base_uri, options = {})
+      options = options.symbolize_keys
+      @base_uri = base_uri
+      @root_path = options.delete(:root_path) || '/'
+      @logger = options.delete(:logger) || NullLogger.new
+      @default_headers = options.delete(:default_headers) || {'Accept' => 'application/json'}
+      @connection = Restfully.adapter.new(@base_uri, options.merge(:logger => @logger))
+      @root = Resource.new(URI.parse(@root_path), self)
+      yield @root.load, self if block_given?
     end
     
-    # TODO: uniformize headers hash (should accept symbols and strings in any capitalization format)
     # TODO: inspect response headers to determine which methods are available
-    def get(path, headers = {})
-      headers = headers.symbolize_keys
-      headers[:accept] ||= 'application/json'
-      logger.info "GET #{path} #{headers.inspect}"
-      # TODO: should be able to choose HTTP lib to use, so we must provide abstract interface for HTTP handlers
-      api = path.empty? ? connection : connection[path]
-      response = api.get(headers)
-      parse response#, :content_type => response.headers['Content-Type']
-      # response = connection.get(path, headers)
-      # logger.info response.headers
-      # logger.info response.status
-      # if (200..300).include?(response.status)
-        # parse response.body, :content_type => response.headers['Content-Type']
-      # else
-        # TODO: better error management ;-)
-        # raise HTTPError.new("Error: #{response.status}")
-      # end
+    def get(path, options = {})
+      path = path.to_s
+      options = options.symbolize_keys
+      uri = URI.parse(base_uri)
+      path_uri = URI.parse(path)
+      # if the given path is complete URL, forget the base_uri, else append the path to the base_uri
+      unless path_uri.scheme.nil?
+        uri = path_uri
+      else  
+        uri.path << path
+      end
+      request = HTTP::Request.new(uri, :headers => options.delete(:headers) || {}, :query => options.delete(:query) || {})
+      request.add_headers(@default_headers) unless @default_headers.empty?
+      logger.info "GET #{request.uri}, #{request.headers.inspect}"
+      response = connection.get(request)
+      logger.debug "Response to GET #{request.uri}: #{response.headers.inspect}"
+      response = deal_with_eventual_errors(response, request)
     end
-  
-    # TODO: add other HTTP methods
+    
+    protected
+    def deal_with_eventual_errors(response, request)
+      case response.status
+      when 400..499
+        # should retry on 406 with another Accept header
+        raise Restfully::HTTP::ClientError, response
+      when 500..599  
+        raise Restfully::HTTP::ServerError, response
+      else
+        response
+      end
+    end
+
   end
 end