restfully 0.2.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Cyril Rohr
+
+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.rdoc

@@ -0,0 +1,90 @@
+= restfully
+
+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.
+
+== 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
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull).
+* Send me a pull request. Bonus points for topic branches.
+
+== Testing
+
+* rake spec, or
+* run autotest in the project directory.
+
+== Copyright
+
+Copyright (c) 2009 Cyril Rohr. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,75 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "restfully"
+    gem.summary = %Q{Experimental code for auto-generation of wrappers on top of RESTful APIs that follow some specific conventions.}
+    gem.description = %Q{Experimental code for auto-generation of wrappers on top of RESTful APIs that follow HATEOAS principles and provide OPTIONS methods and/or Allow headers.}
+    gem.email = "cyril.rohr@gmail.com"
+    gem.homepage = "http://github.com/crohr/restfully"
+    gem.authors = ["Cyril Rohr"]
+    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
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  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'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/the-perfect-gem/"
+        local_dir = 'rdoc'
+
+        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

@@ -0,0 +1 @@
+0.2.1

data/bin/restfully

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# The command line Restfully client
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'restfully'
+require 'optparse'
+require 'logger'
+require 'pp'
+
+@options = {}
+option_parser = OptionParser.new do |opts|
+  opts.banner = "Usage: restfully base_uri [root_path] [options]"
+
+  opts.on("-u=", "--username=", "Sets the username") do |u|
+    @options['username'] = u
+  end
+  opts.on("-p=", "--password=", "Sets the user password") do |p|
+    @options['password'] = p
+  end
+  opts.on("-c=", "--config=", "Sets the various options based on a custom YAML configuration file") do |v|
+    @options['configuration_file'] = v
+  end
+  opts.on("-v", "--verbose", "Run verbosely") do |v|
+    @options['verbose'] = v
+  end
+  opts.on("--log=", "Outputs log messages to the given file. Defaults to stdout") do |v|
+    @options['log'] = v
+  end
+  
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+  
+end
+
+option_parser.parse!
+
+@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_uri = config.delete('base_uri') || @base_uri
+  @root_path = config.delete('root_path') || @root_path
+  @options.merge!(config)
+end
+
+unless @base_uri
+  $stderr.puts option_parser.help
+  exit(-1)
+else
+  if (log_file=@options.delete('log'))
+    @logger = Logger.new(File.expand_path(log_file))
+  else
+    @logger = Logger.new(STDOUT)
+  end
+  if @options.delete('verbose')
+    @logger.level = Logger::DEBUG
+  else
+    @logger.level = Logger::WARN
+  end
+
+  def session
+    @session ||= Restfully::Session.new(@base_uri, @options.merge('root_path' => @root_path, 'logger' => @logger))
+  end
+  def root 
+    @root ||= Restfully::Resource.new(session.root_path, session).load
+  end
+  
+  root # preloads
+  
+  require 'irb'
+  require 'irb/completion'
+  
+  ARGV.clear
+  IRB.start
+  exit!
+end

data/examples/grid5000.rb

@@ -0,0 +1,28 @@
+require 'rubygems'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'pp'
+
+require File.dirname(__FILE__)+'/../lib/restfully'
+
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+
+# Restfully.adapter = Restfully::HTTP::RestClientAdapter
+# Restfully.adapter = Patron::Session
+RestClient.log = 'stdout'
+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)|
+      accu['hardware'][node_status['hardware_state']] = (accu['hardware'][node_status['hardware_state']] || 0) + 1
+      accu['system'][node_status['system_state']] = (accu['system'][node_status['system_state']] || 0) + 1
+      accu
+    }
+    grid_stats['hardware'].merge!(site_stats['hardware']) { |key,oldval,newval| oldval+newval }
+    grid_stats['system'].merge!(site_stats['system']) { |key,oldval,newval| oldval+newval }
+    p [site_uid, site_stats]
+  end
+  p [:total, grid_stats]
+  puts "Getting status of a few nodes in rennes:"
+  pp grid.sites['rennes'].status(:query => {:only => ['paradent-1', 'paradent-10', 'paramount-3']})
+end

data/lib/restfully.rb

@@ -0,0 +1,19 @@
+require 'restfully/error'
+require 'restfully/parsing'
+require 'restfully/http'
+require 'restfully/http/adapters/rest_client_adapter'
+require 'restfully/extensions'
+require 'restfully/session'
+require 'restfully/special_hash'
+require 'restfully/special_array'
+require 'restfully/link'
+require 'restfully/resource'
+require 'restfully/collection'
+
+
+module Restfully  
+  class << self
+    attr_accessor :adapter
+  end
+  self.adapter = Restfully::HTTP::Adapters::RestClientAdapter
+end

data/lib/restfully/collection.rb

@@ -0,0 +1,63 @@
+require 'delegate'
+
+module Restfully
+  class Collection < DelegateClass(Hash)
+    
+    attr_reader :state, :raw, :uri, :session, :title
+    
+    def initialize(uri, session, options = {})
+      options = options.symbolize_keys
+      @uri = uri
+      @title = options[:title]
+      @session = session
+      @raw = options[:raw]
+      @state = :unloaded
+      @items = {}
+      super(@items)
+    end
+    
+    def loaded?;    @state == :loaded;    end
+    
+    def load(options = {})
+      options = options.symbolize_keys
+      force_reload = !!options.delete(:reload) || options.has_key?(:query)
+      if loaded? && !force_reload
+        self
+      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)
+          else
+            session.logger.warn "Resource #{key} does not have a 'self' link. skipped."
+          end
+        end       
+        @state = :loaded
+        self
+      end
+    end
+    
+    def inspect(options = {:space => "\t"})
+      output = "#<#{self.class}:0x#{self.object_id.to_s(16)}"
+      if loaded?
+        output += "\n#{options[:space]}------------ META ------------"
+        output += "\n#{options[:space]}@uri: #{uri.inspect}"
+        unless @items.empty?        
+          output += "\n#{options[:space]}------------ PROPERTIES ------------"
+          @items.each do |key, value|
+            output += "\n#{options[:space]}#{key.inspect} => #{value.class.name}"
+          end
+        end
+      end
+      output += ">"
+    end
+    
+    
+  end
+end

data/lib/restfully/error.rb

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

data/lib/restfully/extensions.rb

@@ -0,0 +1,41 @@
+class BasicObject #:nodoc:
+  instance_methods.each { |m| undef_method m unless m =~ /^__|instance_eval/ }
+end unless defined?(BasicObject)
+
+# monkey patching:
+class Hash
+  # Taken from ActiveSupport
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end
+
+  # Taken from ActiveSupport  
+  def stringify_keys
+    inject({}) do |options, (key, value)|
+      options[key.to_s] = value
+      options
+    end
+  end
+
+
+  # This is by no means the standard way to transform ruby objects into query parameters
+  # but it is targeted at our own needs
+  def to_params
+    params = ''
+
+    each do |k, v|
+      if v.is_a?(Array)
+        params << "#{k}=#{v.join(",")}&"
+      else
+        params << "#{k}=#{v.to_s}&"
+      end
+    end
+
+    params.chop! 
+    params
+  end
+
+end