restfully 0.3.2 → 0.4.0

data/lib/restfully/session.rb

@@ -10,7 +10,7 @@ module Restfully
   end
   class Session
     include Parsing, HTTP::Headers
-    attr_reader :base_uri, :root_path, :logger, :connection, :root, :default_headers
+    attr_reader :base_uri, :logger, :connection, :root, :default_headers
     
     # TODO: use CacheableResource
     def initialize(options = {})
@@ -18,38 +18,52 @@ module Restfully
       if (config_filename = options.delete(:configuration_file)) && File.exists?(File.expand_path(config_filename))
         config = YAML.load_file(File.expand_path(config_filename)).symbolize_keys
         options.merge!(config)
-      end  
-      @base_uri               =   options.delete(:base_uri) || "http://localhost:8888"
-      @root_path              =   options.delete(:root_path) || "/"
+      end
+      @base_uri               =   URI.parse(options.delete(:base_uri) || "http://localhost:8888") rescue nil
+      raise ArgumentError.new("#{@base_uri} is not a valid URI") if @base_uri.nil? || @base_uri.scheme !~ /^http/i
       @logger                 =   options.delete(:logger) || NullLogger.new
+      @logger.level           =   options.delete(:verbose) ? Logger::DEBUG : @logger.level
       user_default_headers    =   sanitize_http_headers(options.delete(:default_headers) || {})
       @default_headers        =   {'User-Agent' => "Restfully/#{Restfully::VERSION}", 'Accept' => 'application/json'}.merge(user_default_headers)
-      @connection = Restfully.adapter.new(@base_uri, options.merge(:logger => @logger))
-      @root = Resource.new(URI.parse(@root_path), self)
+      @connection             =   Restfully.adapter.new(base_uri.to_s, options.merge(:logger => logger))
+      @root                   =   Resource.new(@base_uri, self)
       yield @root.load, self if block_given?
     end
     
-    # TODO: inspect response headers to determine which methods are available
+    # returns an HTTP::Response object or raise a Restfully::HTTP::Error
+    def head(path, options = {})
+      options = options.symbolize_keys
+      transmit :head, HTTP::Request.new(uri_for(path), :headers => options.delete(:headers), :query => options.delete(:query))
+    end
+    
+    # returns an HTTP::Response object or raise a Restfully::HTTP::Error
     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)
+      transmit :get, HTTP::Request.new(uri_for(path), :headers => options.delete(:headers), :query => options.delete(:query))
+    end
+    
+    # returns an HTTP::Response object or raise a Restfully::HTTP::Error
+    def post(path, body, options = {})
+      options = options.symbolize_keys
+      uri = uri_for(path)
+      transmit :post, HTTP::Request.new(uri_for(path), :body => body, :headers => options.delete(:headers), :query => options.delete(:query))
+    end
+    
+    # builds the complete URI, based on the given path and the session's base_uri
+    def uri_for(path)
+      URI.join(base_uri.to_s, path.to_s)
     end
     
     protected
+    def transmit(method, request)
+      request.add_headers(default_headers) unless default_headers.empty?
+      logger.info "#{method.to_s.upcase} #{request.uri}"  +
+                  "\nHeaders: #{request.headers.inspect}" +
+                  "#{request.body ? "\nBody: #{request.body.length} bytes" : ""}"
+      response = connection.send(method.to_sym, request)
+      response = deal_with_eventual_errors(response, request)
+    end
+    
     def deal_with_eventual_errors(response, request)
       case response.status
       when 400..499

data/restfully.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{restfully}
-  s.version = "0.3.2"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Cyril Rohr"]
-  s.date = %q{2009-11-02}
+  s.date = %q{2009-11-16}
   s.default_executable = %q{restfully}
   s.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.}
   s.email = %q{cyril.rohr@gmail.com}
@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
      ".gitignore",
+     "CHANGELOG",
      "LICENSE",
      "README.rdoc",
      "Rakefile",
@@ -89,10 +90,14 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rest-client>, [">= 1.0"])
+      s.add_runtime_dependency(%q<backports>, [">= 0"])
     else
       s.add_dependency(%q<rest-client>, [">= 1.0"])
+      s.add_dependency(%q<backports>, [">= 0"])
     end
   else
     s.add_dependency(%q<rest-client>, [">= 1.0"])
+    s.add_dependency(%q<backports>, [">= 0"])
   end
 end
+

data/spec/collection_spec.rb

@@ -4,53 +4,54 @@ include Restfully
 describe Collection do
   describe "general behaviour" do
     before do
-      @collection = Collection.new("uri", session=mock('session')).load(:raw => JSON.parse(fixture("grid5000-sites.json")))
+      @uri = URI.parse('http://api.local/x/y/z')
+      @collection = Collection.new(@uri, session=mock('session')).load(:body => JSON.parse(fixture("grid5000-sites.json")))
     end
     it "should be enumerable" do
       @collection.length.should == 9
+      @collection.size.should == 9
       @collection.map{|site| site["uid"]}.sort.should == ["bordeaux", "grenoble", "lille", "lyon", "nancy", "orsay", "rennes", "sophia", "toulouse"]
     end
   
-    it "should have a :total method" do
-      @collection.total.should == 9
+    it "should have a :total attribute" do
+      @collection["total"].should == 9
     end
   
-    it "should have a :offset method" do
-      @collection.offset.should == 0
+    it "should have a :offset attribute" do
+      @collection["offset"].should == 0
     end
   end  
   
   describe "loading" do
     before(:all) do
+      @uri = URI.parse('http://api.local/x/y/z')
       @raw = fixture("grid5000-sites.json")
       @response_200 = Restfully::HTTP::Response.new(200, {'Content-Type' => 'application/json;charset=utf-8', 'Content-Length' => @raw.length}, @raw)
       @logger = Logger.new(STDOUT)
     end
     it "should not load if already loaded and no :reload" do
-      collection = Collection.new("uri", mock("session"))
-      collection.should_receive(:loaded?).and_return(true)
-      collection.instance_variable_set(:@last_request_hash, [:get, {}].hash)
-      collection.load(:reload => false).should == collection
+      collection = Collection.new(@uri, mock("session"))
+      options = {:headers => {'key' => 'value'}}
+      collection.should_receive(:executed_requests).and_return({'GET' => {'options' => options, 'body' => {"key", "value"}}})
+      collection.load(options.merge(:reload => false)).should == collection
     end
     it "should load when :reload param is true [already loaded]" do
-      collection = Collection.new("uri", session=mock("session", :logger => Logger.new(STDOUT)))
-      collection.should_receive(:loaded?).and_return(true)
+      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
       session.should_receive(:get).and_return(@response_200)
       collection.load(:reload => true).should == collection    
     end
     it "should load when force_reload is true [not loaded]" do
-      collection = Collection.new("uri", session=mock("session", :logger => Logger.new(STDOUT)))
-      collection.should_receive(:loaded?).and_return(false)
+      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
       session.should_receive(:get).and_return(@response_200)
       collection.load(:reload => true).should == collection    
     end
     it "should force reload when query parameters are given" do
-      collection = Collection.new("uri", session=mock("session", :logger => Logger.new(STDOUT)))
+      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT)))
       session.should_receive(:get).and_return(@response_200)
       collection.load(:query => {:q1 => 'v1'}).should == collection
     end
     it "should not initialize resources lacking a self link" do
-      collection = Collection.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      collection = Collection.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         "total" => 1,
         "offset" => 0,
         "items" => [
@@ -64,10 +65,10 @@ describe Collection do
       }), :logger => @logger))
       Resource.should_not_receive(:new)
       collection.load
-      collection.by_uid('rennes').should be_nil
+      collection.find{|i| i['uid'] == 'rennes'}.should be_nil
     end
     it "should initialize resources having a self link" do
-      collection = Collection.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      collection = Collection.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         "total" => 1,
         "offset" => 0,
         "items" => [
@@ -82,17 +83,15 @@ describe Collection do
       }), :logger => @logger))
       collection.load
       collection.length.should == 1
-      collection.by_uid('rennes').class.should == Restfully::Resource
+      collection.find{|i| i['uid'] == 'rennes'}.class.should == Restfully::Resource
     end
     it "should correctly initialize its resources [integration test]" do
-      collection = Collection.new("uri", session=mock("session", :logger => Logger.new(STDOUT), :get => @response_200))
+      collection = Collection.new(@uri, session=mock("session", :logger => Logger.new(STDOUT), :get => @response_200))
       collection.load
-      collection.should be_loaded
-      collection.uri.should == "uri"
-      collection.by_uid('rennes')["uid"].should == 'rennes'
-      collection.by_uid('rennes')["type"].should == 'site'
-      collection.by_uid.keys.should =~ ['rennes', 'lille', 'bordeaux', 'nancy', 'sophia', 'toulouse', 'lyon', 'grenoble', 'orsay']
-      collection.by_uid('rennes', 'bordeaux').length.should == 2
+      collection.uri.should == @uri
+      collection.find{|i| i['uid'] == 'rennes'}["uid"].should == 'rennes'
+      collection.find{|i| i['uid'] == 'rennes'}["type"].should == 'site'
+      collection.map{|s| s['uid']}.should =~ ['rennes', 'lille', 'bordeaux', 'nancy', 'sophia', 'toulouse', 'lyon', 'grenoble', 'orsay']
     end 
   end
   

data/spec/http/request_spec.rb

@@ -4,16 +4,20 @@ describe Restfully::HTTP::Request do
   it "should correctly initialize the attributes" do
     request = Restfully::HTTP::Request.new(
       'https://api.grid5000.fr/sid/grid5000?q1=v1&q2=v2', 
-      :headers => {'accept' => 'application/json', :cache_control => 'max-age=0'}, 
-      :query => {'custom_param1' => [3, 4, 5, 6], 'custom_param2' => 'value_custom_param2'}
+      :headers => {'accept' => 'application/json', :cache_control => 'max-age=0', 'Content-Type' => 'application/json'}, 
+      :query => {'custom_param1' => [3, 4, 5, 6], 'custom_param2' => 'value_custom_param2'},
+      :body => {"key" => "value"}.to_json
     )
     request.uri.should be_a URI
     request.uri.to_s.should == 'https://api.grid5000.fr/sid/grid5000?q1=v1&q2=v2&custom_param1=3,4,5,6&custom_param2=value_custom_param2'
     request.uri.query.should == "q1=v1&q2=v2&custom_param1=3,4,5,6&custom_param2=value_custom_param2"
     request.headers.should == {
+      "Content-Type"=>"application/json", 
       'Accept' => 'application/json',
       'Cache-Control' => 'max-age=0'
     }
+    request.body.should == {"key" => "value"}
+    request.raw_body.should == "{\"key\":\"value\"}"
     request.retries.should == 0
   end
   

data/spec/http/response_spec.rb

@@ -12,4 +12,8 @@ describe Restfully::HTTP::Response do
       'property2' => 'value2'
     }
   end
+  it "should return the unserialized body" do
+    response = Restfully::HTTP::Response.new(404, {:content_type => 'application/json;charset=utf-8'}, '{"property1": "value1", "property2": "value2"}')
+    response.raw_body.should == "{\"property1\": \"value1\", \"property2\": \"value2\"}"
+  end
 end

data/spec/http/rest_client_adapter_spec.rb

@@ -19,7 +19,7 @@ describe Restfully::HTTP::Adapters::RestClientAdapter do
   end
   it "should raise a not implemented error when trying to use functions not implemented yet" do
     adapter = Restfully::HTTP::Adapters::RestClientAdapter.new("https://api.grid5000.fr")
-    lambda{adapter.post(mock("restfully request"))}.should raise_error NotImplementedError, "POST is not supported by your adapter."
+    lambda{adapter.delete(mock("restfully request"))}.should raise_error NotImplementedError, "DELETE is not supported by your adapter."
   end
   it "should rescue any RestClient::Exception and correctly populate the response" do
     res = mock(Net::HTTPResponse, :code => 404, :body => '{"message":"whatever"}', :to_hash => {'Content-Type' => 'application/json;charset=utf-8', 'Content-Length' => 22}, :[] => '')
@@ -28,6 +28,7 @@ describe Restfully::HTTP::Adapters::RestClientAdapter do
     response = adapter.get(mock("request", :uri => "uri"))
     response.status.should == 404
     response.headers.should == {'Content-Type' => 'application/json;charset=utf-8', 'Content-Length' => 22}
-    response.body.should == {'message' => 'whatever'}
+    response.raw_body.should == '{"message":"whatever"}'
+    response.body.should == {"message"=>"whatever"}
   end
 end

data/spec/link_spec.rb

@@ -2,7 +2,9 @@ require File.expand_path(File.dirname(__FILE__)+'/spec_helper')
 
 include Restfully
 describe Link do
-
+  before do
+    @uri = URI.parse('/x/y/z')
+  end
   it "should have a rel reader" do
     link = Link.new
     link.should_not respond_to(:rel=)
@@ -28,7 +30,7 @@ describe Link do
     link.should respond_to(:valid?)    
   end
   it "should respond to resolved?" do
-    link = Link.new
+    link = Link.new("href" => @uri)
     link.should respond_to(:resolved?)
   end
   it "should respond to resolvable?" do
@@ -43,9 +45,10 @@ describe Link do
     link = Link.new
     link.should_not be_resolved
   end
-  it "should not be valid if there is no href" do
+  it "should be valid even if the href is ''" do
     link = Link.new 'rel' => 'collection', 'title' => 'my collection'
-    link.should_not be_valid
+    link.should be_valid
+    link.href.should == URI.parse("")
   end
   it "should not be valid if there is no rel" do
     link = Link.new 'href' => '/', 'title' => 'my collection'

data/spec/resource_spec.rb

@@ -7,16 +7,6 @@ describe Resource do
     @logger = Logger.new(STDOUT)
   end
   
-  it "should have all the methods of a hash" do
-    resource = Resource.new("uri", session=mock('session'))
-    resource.size.should == 0
-    resource['whatever'] = 'thing'
-    resource.size.should == 1
-    resource.should == {'whatever' => 'thing'}
-    resource.should respond_to(:each)
-    resource.should respond_to(:length)
-  end
-  
   describe "accessors" do
     it "should have a reader on the session" do
       resource = Resource.new("uri", session=mock("session"))
@@ -26,17 +16,7 @@ describe Resource do
     it "should have a reader on the uri" do
       resource = Resource.new("uri", session=mock("session"))
       resource.should_not respond_to(:uri=)
-      resource.uri.should == "uri"
-    end
-    it "should have a reader on the raw property" do
-      resource = Resource.new("uri", session=mock("session"))
-      resource.should_not respond_to(:raw=)
-      resource.load('raw' => {:a => :b}).raw.should == {:a => :b}
-    end
-    it "should have a reader on the state property" do
-      resource = Resource.new("uri", session=mock("session"))
-      resource.should_not respond_to(:state=)
-      resource.state.should == :unloaded
+      resource.uri.should == URI.parse("uri")
     end
   end
   
@@ -85,97 +65,92 @@ describe Resource do
             'model' => 'XYZ1b'
           }
         }
-      }.to_json
-      @response_200 = Restfully::HTTP::Response.new(200, {'Content-Type' => 'application/json;utf-8', 'Content-Length' => @raw.length}, @raw)
+      }
+      @response_200 = Restfully::HTTP::Response.new(200, {'Content-Type' => 'application/json;utf-8', 'Content-Length' => @raw.length}, @raw.to_json)
+      @uri = URI.parse("http://api.local/x/y/z")
     end
     it "should not be loaded in its initial state" do
-      resource = Resource.new(mock("uri"), mock('session'))
-      resource.should_not be_loaded
+      resource = Resource.new(@uri, mock('session'))
+      resource.executed_requests.should == {}
     end
     it "should get the raw representation of the resource via the session if it doesn't have it" do
-      resource = Resource.new(uri=mock("uri"), session = mock("session", :logger => Logger.new(STDOUT)))
+      resource = Resource.new(@uri, session = mock("session", :logger => Logger.new(STDOUT)))
       resource.stub!(:define_link) # do not define links
-      resource.raw.should be_nil
-      session.should_receive(:get).with(uri, {}).and_return(@response_200)
+      session.should_receive(:get).with(@uri, {}).and_return(@response_200)
       resource.load
-      resource.should be_loaded
     end
     it "should get the raw representation of the resource via the session if there are query parameters" do
-      resource = Resource.new(uri=mock("uri"), session = mock("session", :logger => Logger.new(STDOUT)))
+      resource = Resource.new(@uri, session = mock("session", :logger => Logger.new(STDOUT)))
       resource.stub!(:define_link) # do not define links
-      resource.stub!(:loaded?).and_return(true) # should force reload even if already loaded
-      resource.raw.should be_nil
-      session.should_receive(:get).with(uri, {:query => {:q1 => 'v1'}}).and_return(@response_200)
+      session.should_receive(:get).with(@uri, {:query => {:q1 => 'v1'}}).and_return(@response_200)
       resource.load(:query => {:q1 => 'v1'})
     end
     it "should get the raw representation of the resource if forced to do so" do
-      resource = Resource.new(uri=mock("uri"), session = mock("session", :logger => Logger.new(STDOUT)))
+      resource = Resource.new(@uri, session = mock("session", :logger => Logger.new(STDOUT)))
       resource.stub!(:define_link) # do not define links
-      resource.stub!(:loaded?).and_return(true) # should force reload even if already loaded
-      resource.raw.should be_nil
-      session.should_receive(:get).with(uri, {}).and_return(@response_200)
+      session.should_receive(:get).with(@uri, {}).and_return(@response_200)
       resource.load(:reload => true)
     end
     it "should correctly define the functions to access simple values" do
-      resource = Resource.new("uri", session = mock("session", :get => @response_200, :logger => @logger))
+      resource = Resource.new(@uri, session = mock("session", :get => @response_200, :logger => @logger))
       resource.stub!(:define_link) # do not define links
       resource.load
       resource['whatever'].should == 'whatever'
-      resource.uri.should == 'uri'
+      resource.uri.should == @uri
       resource["uid"].should == 'rennes'
       resource['an_array'].should be_a(SpecialArray)
       resource['an_array'].should == [1,2,3]
       lambda{resource.clusters}.should raise_error(NoMethodError)
     end
     
-    it "should correctly define a collection association" do
-      resource = Resource.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+    it "should correctly define a collection link" do
+      resource = Resource.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         'links' => [
           {'rel' => 'self', 'href' => '/grid5000/sites/rennes'},
           {'rel' => 'collection', 'href' => '/grid5000/sites/rennes/versions', 'resolvable' => false, 'title' => 'versions'}
         ],
         'uid' => 'rennes'
       }), :logger => @logger))
-      Collection.should_receive(:new).with('/grid5000/sites/rennes/versions', session, :title => 'versions', :raw => nil).and_return(collection=mock("restfully collection"))
+      Collection.should_receive(:new).with(@uri.merge('/grid5000/sites/rennes/versions'), session, :title => 'versions').and_return(collection=mock("restfully collection"))
       resource.load
-      resource.associations['versions'].should == collection
+      resource.links['versions'].should == collection
     end
     it "should NOT update the URI with the self link" do
-      resource = Resource.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      resource = Resource.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         'links' => [
           {'rel' => 'self', 'href' => '/grid5000/sites/rennes'}
         ],
         'uid' => 'rennes'
       }), :logger => @logger))
-      resource.uri.should == "uri"
+      resource.uri.should == @uri
       resource.load
-      resource.uri.should == "uri"
+      resource.uri.should == @uri
     end
     it "should correctly define a member association" do
-      resource = Resource.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      resource = Resource.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         'links' => [
           {'rel' => 'member', 'href' => '/grid5000/sites/rennes/versions/123', 'title' => 'version'}
         ],
         'uid' => 'rennes'
       }), :logger => @logger))
-      Resource.should_receive(:new).with('/grid5000/sites/rennes/versions/123', session, :title => 'version', :raw => nil).and_return(member=mock("restfully resource"))
+      Resource.should_receive(:new).with(@uri.merge('/grid5000/sites/rennes/versions/123'), session, :title => 'version').and_return(member=mock("restfully resource"))
       resource.load
-      resource.associations['version'].should == member
+      resource.links['version'].should == member
     end
     it "should correctly define a parent association" do
-      resource = Resource.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      resource = Resource.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         'links' => [
           {'rel' => 'self', 'href' => '/grid5000/sites/rennes'},
           {'rel' => 'parent', 'href' => '/grid5000'}
         ],
         'uid' => 'rennes'
       }), :logger => @logger))
-      Resource.should_receive(:new).with('/grid5000', session).and_return(parent=mock("restfully resource"))
+      Resource.should_receive(:new).with(@uri.merge('/grid5000'), session).and_return(parent=mock("restfully resource"))
       resource.load
-      resource.associations['parent'].should == parent
+      resource.links['parent'].should == parent
     end
     it "should ignore bad links" do
-      resource = Resource.new("uri", session = mock("session", :get => mock("restfully response", :body => {
+      resource = Resource.new(@uri, session = mock("session", :get => mock("restfully response", :body => {
         'links' => [
           {'rel' => 'self', 'href' => '/grid5000/sites/rennes'},
           {'rel' => 'invalid_rel', 'href' => '/whatever'},
@@ -184,15 +159,15 @@ describe Resource do
         'uid' => 'rennes'
       }), :logger => @logger))
       resource.load
-      resource.associations.should be_empty
+      resource.links.should be_empty
     end
     
     it "should correctly define the functions to access links [integration test]" do
-      resource = Resource.new("uri", session = mock("session", :get => @response_200, :logger => @logger))
+      resource = Resource.new(@uri, session = mock("session", :get => @response_200, :logger => @logger))
       @logger.should_receive(:warn).with(/collection \/has\/no\/title has no title/)
       @logger.should_receive(:warn).with(/invalid_rel is not a valid link relationship/)
       resource.load
-      resource.associations.keys.should =~ ['versions', 'clusters', 'environments', 'status', 'parent', 'version']
+      resource.links.keys.should =~ ['versions', 'clusters', 'environments', 'status', 'parent', 'version']
     end
   end
 end