restfully 0.2.1

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/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/link.rb

@@ -0,0 +1,35 @@
+module Restfully
+  class Link
+    
+    VALID_RELATIONSHIPS = %w{member parent collection self alternate}
+    RELATIONSHIPS_REQUIRING_TITLE = %w{collection member}
+    
+    attr_reader :rel, :title, :href, :errors
+    
+    def initialize(attributes = {})
+      @rel = attributes['rel']
+      @title = attributes['title']
+      @href = attributes['href']
+      @resolvable = attributes['resolvable'] || false
+      @resolved = attributes['resolved'] || false
+    end
+    
+    def resolvable?; @resolvable == true; end
+    def resolved?; @resolved == true; end
+    def self?; @rel == 'self'; end
+    
+    def valid?
+      @errors = []
+      if href.nil? || href.empty?
+        errors << "href cannot be empty."
+      end
+      unless VALID_RELATIONSHIPS.include?(rel)
+        errors << "#{rel} is not a valid link relationship."
+      end
+      if (!title || title.empty?) && RELATIONSHIPS_REQUIRING_TITLE.include?(rel)
+        errors << "#{rel} #{href} has no title."
+      end
+      errors.empty?
+    end
+  end
+end

data/lib/restfully/parsing.rb

@@ -0,0 +1,31 @@
+require 'json'
+
+module Restfully
+  
+  module Parsing
+  
+    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)
+      case content_type
+      when /^application\/json/i
+        JSON.parse(object)
+      else
+        raise ParserNotFound.new("Content-Type '#{content_type}' is not supported. Cannot parse the given object.")
+      end
+    end
+  
+    def serialize(object, options = {})
+      content_type = options[:content_type]
+      content_type ||= object.headers['Content-Type'] if object.respond_to?(:headers)
+      case content_type
+      when /^application\/json/i
+        JSON.dump(object)
+      else
+        raise ParserNotFound, [object, content_type]
+      end
+    end
+
+  end
+end

data/lib/restfully/resource.rb

@@ -0,0 +1,117 @@
+require 'delegate'
+
+module Restfully
+  
+  # Suppose that the load method has been called on the resource before trying to access its attributes or associations
+  
+  class Resource < DelegateClass(Hash)
+    
+    undef :type
+    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]
+      @state = :unloaded
+      @attributes = {}
+      super(@attributes)
+      @associations = {}
+    end
+    
+    def loaded?;    @state == :loaded;    end
+    
+    def method_missing(method, *args)
+      if association = @associations[method.to_s]
+        session.logger.debug "Loading association #{method}, args=#{args.inspect}"
+        association.load(*args)
+      else
+        super(method, *args)
+      end
+    end
+  
+    def load(options = {})
+      options = options.symbolize_keys
+      force_reload = !!options.delete(:reload) || options.has_key?(:query)
+      if loaded? && !force_reload
+        self
+      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
+          when 'links'  then  next
+          when 'uid'    then  @uid = value
+          when 'type'   then  @type = value
+          else
+            case value
+            when Hash
+              @attributes.store(key, SpecialHash.new.replace(value)) unless @associations.has_key?(key)
+            when Array
+              @attributes.store(key, SpecialArray.new(value))
+            else
+              @attributes.store(key, value)
+            end
+          end
+        end
+        @state = :loaded
+        self
+      end
+    end
+    
+    def respond_to?(method, *args)
+      @associations.has_key?(method.to_s) || super(method, *args)
+    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}"
+        output += "\n#{options[:space]}@uid: #{uid.inspect}"
+        output += "\n#{options[:space]}@type: #{type.inspect}"
+        @associations.each do |title, assoc|
+          output += "\n#{options[:space]}@#{title}: #{assoc.class.name}"
+        end
+        unless @attributes.empty?
+          output += "\n#{options[:space]}------------ PROPERTIES ------------"
+          @attributes.each do |key, value|
+            output += "\n#{options[:space]}#{key.inspect} => #{value.inspect}"
+          end
+        end
+      end
+      output += ">"
+    end    
+    
+    protected
+    def define_link(link)
+      if link.valid?
+        case link.rel
+        when 'parent'
+          @associations['parent'] = Resource.new(link.href, session)
+        when 'collection'
+          raw_included = link.resolved? ? raw[link.title] : nil
+          @associations[link.title] = Collection.new(link.href, session, 
+            :raw => raw_included,
+            :title => link.title)
+        when 'member'
+          raw_included = link.resolved? ? raw[link.title] : nil
+          @associations[link.title] = Resource.new(link.href, session, 
+            :title => link.title,
+            :raw => raw_included)
+        when 'self'
+          # we do nothing
+        end
+      else 
+        session.logger.warn link.errors.join("\n")
+      end
+    end
+    
+  end # class Resource
+end # module Restfully

data/lib/restfully/session.rb

@@ -0,0 +1,61 @@
+require 'uri'
+require 'logger'
+require 'restfully/parsing'
+
+module Restfully
+  class NullLogger
+    def method_missing(method, *args)
+      nil
+    end
+  end
+  class Session
+    include Parsing
+    attr_reader :base_uri, :root_path, :logger, :connection, :root, :default_headers
+    
+    # TODO: use CacheableResource
+    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: inspect response headers to determine which methods are available
+    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
+    
+    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

data/lib/restfully/special_array.rb

@@ -0,0 +1,5 @@
+module Restfully
+  # To be used to provide facilities such as hash-like lookups
+  class SpecialArray < Array
+  end
+end

data/lib/restfully/special_hash.rb

@@ -0,0 +1,5 @@
+module Restfully
+  # To be used later
+  class SpecialHash < Hash
+  end
+end