harpy 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,3 @@
+-I lib
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in harpy.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+harpy is Copyright © 2011 TalentBox SA
+
+MIT License
+
+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.md

@@ -0,0 +1,168 @@
+Harpy
+======
+
+Client for REST API with HATEOAS
+
+Dependencies
+------------
+
+* Ruby 1.8.7 or 1.9.2
+* gem "typhoeus", "~> 0.2.4"
+* gem "activesupport", ">= 3.0.0"
+* gem "activemodel", ">= 3.0.0"
+* gem "hash-deep-merge", "~> 0.1.1"
+* gem "yajl-ruby", "~> 0.8.2"
+
+Usage
+-----
+
+* Set entry_point url:
+
+        Harpy.entry_point_url = "http://localhost"
+
+* Include `Harpy::Resource` in your model:
+
+        class MyModel
+          include Harpy::Resource
+        end
+
+        # Mass assignment
+        model = MyModel.new "firstname" => "Anthony", "lastname" => "Stark"
+        model.attributes = {"company" => "Stark Enterprises"}
+        model.firstname # => "Anthony"
+        model.company # => "Stark Enterprises"
+        
+        # Because model is not persisted you can read any attribute, allowing
+        # to use form_for on new resources to which the client doesn't know the
+        # existing attributes yet
+        model.email # => nil
+
+        # Fetch by url
+        MyModel.from_url "http://localhost/mymodel/1" 
+        # => instance of MyModel with attributes filled in on 200
+        # => nil on 404
+        # => raises Harpy::ClientTimeout on timeout
+        # => raises Harpy::ClientError on Curl error
+        # => raises Harpy::InvalidResponseCode on other response codes
+
+        # Fetch multiple by url in parallel
+        MyModel.from_url ["http://localhost/mymodel/1", "http://localhost/mymodel/2"]
+        
+        # Get index
+        MyModel.search
+        # will call GET http://localhost/mymodel given the following entry_point response:
+          {
+            "link": [
+              {"rel": "my_model", "href": "http://localhost/mymodel"}
+            ]
+          }
+        # => return an array of MyModel instances on 200
+        # => raises Harpy::ClientTimeout on timeout
+        # => raises Harpy::ClientError on Curl error
+        # => raises Harpy::InvalidResponseCode on other response codes
+        
+        # Search by first_name
+        MyModel.search :firstname => "Anthony" # GET http://localhost/mymodel?firstname=Anthony
+
+        # Create (POST)
+        model = MyModel.new "firstname" => "Anthony"
+        model.save # POST http://localhost/mymodel with {"firstname":"Anthony"}
+
+        # Get an existing resource by url:
+        model = MyModel.from_url "http://localhost/mymodel/1"
+        # if the service returns the following response:
+          {
+            "firstname": "Anthony",
+            "lastname": null,
+            "urn": "urn:mycompany:mymodel:1"
+            "link" => [
+              {"rel" => "self", "href" => "http://localhost/mymodel/1"},
+              {"rel" => "accounts", "href" => "http://localhost/mymodel/1/accounts"}
+            ]
+          }
+        # we can then do:
+        model.firstname # => "Anthony"
+        model.link "self" # => "http://localhost/mymodel/1"
+        model.link :accounts # => "http://localhost/mymodel/1/accounts"
+
+        # Update (PUT) requires resource to have both urn and link to self
+        model.attributes = {"firstname" => "Tony"}
+        model.save # PUT http://localhost/mymodel/1
+
+        # The resource is persisted once it has an urn:
+        model.persisted? # => true
+
+        # If persisted you can no longer read undefined attributes:
+        model.lastname # => nil
+        model.email # => will raise NoMethodError
+
+* To find a resource by id you need to define `.urn`:
+
+        class MyModel
+          include Harpy::Resource
+          def self.urn(id)
+            "urn:mycompany:mymodel:#{id}"
+          end
+        end
+
+        model = MyModel.from_id 1 # will GET http://localhost/urn:mycompany:mymodel:1
+        # expecting a permanent redirect (301) to follow or not found (404)
+
+* Rel name to search for in entry_point when getting index can be overridden:
+
+        class MyCustomModel
+          include Harpy::Resource
+          def self.resource_name
+            "custom_model"
+          end
+        end
+
+* or you can use `.with_url(url)` for getting index of nested resources:
+
+        class Account
+          include Harpy::Resource
+          def users
+            User.with_url(link "user") do
+              User.search
+            end
+          end
+        end
+        class User
+          include Harpy::Resource
+        end
+
+* you can override `#url_collection` to create nested resources:
+
+        class Account
+          include Harpy::Resource
+        end
+        class User
+          include Harpy::Resource
+          attr_accessor :account
+          def url_collection
+            account ? account.link("user") : super
+          end
+        end
+
+* Fetch multiple resources in parallel:
+
+        class FirstModel
+          include Harpy::Resource
+        end
+        class SecondModel
+          include Harpy::Resource
+        end
+      
+        Harpy::Resource.from_url({
+           FirstModel => ["http://localhost/firstmodel/1", "http://localhost/firstmodel/2"], 
+           SecondModel => ["http://localhost/secondmodel/1"], 
+        })
+        # => {FirstModel => [...], SecondModel => [...]}
+
+About
+-----
+
+License
+-------
+
+harpy is Copyright © 2011 TalentBox SA. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/harpy.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "harpy/version"
+
+Gem::Specification.new do |s|
+  s.name        = "harpy"
+  s.version     = Harpy::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Joseph HALTER", "Jonathan TRON"]
+  s.email       = ["joseph.halter@thetalentbox.com", "jonathan.tron@thetalentbox.com"]
+  s.homepage    = "https://github.com/TalentBox/harpy"
+  s.summary     = %q{Client for REST API}
+  s.description = %q{Client for REST API with HATEOAS}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency("typhoeus", ["~> 0.2.4"])
+  s.add_runtime_dependency("activesupport", [">= 3.0.0"])
+  s.add_runtime_dependency("activemodel", [">= 3.0.0"])
+  s.add_runtime_dependency("hash-deep-merge", ["~> 0.1.1"])
+  s.add_runtime_dependency("yajl-ruby", ["~> 0.8.2"])
+
+  s.add_development_dependency("rake", ["~> 0.8.7"])
+  s.add_development_dependency("rspec", ["~> 2.6.0"])
+  s.add_development_dependency("rocco", ["~> 0.7"])
+end

data/lib/harpy/client.rb

@@ -0,0 +1,66 @@
+require "typhoeus"
+require "hash_deep_merge"
+
+module Harpy
+  class Client
+    attr_accessor :options
+
+    def initialize(opts=nil)
+      self.options = (opts || {})
+    end
+
+    def get(url_or_urls, opts=nil)
+      request :get, url_or_urls, opts
+    end
+
+    def head(url_or_urls, opts=nil)
+      request :head, url_or_urls, opts
+    end
+
+    def post(url_or_urls, opts=nil)
+      request :post, url_or_urls, opts
+    end
+
+    def put(url_or_urls, opts=nil)
+      request :put, url_or_urls, opts
+    end
+
+    def patch(url_or_urls, opts=nil)
+      request :patch, url_or_urls, opts
+    end
+
+    def delete(url_or_urls, opts=nil)
+      request :delete, url_or_urls, opts
+    end
+
+    def run(requests)
+      requests.each{|request| Typhoeus::Hydra.hydra.queue request}
+      Typhoeus::Hydra.hydra.run
+      requests.collect(&:response)
+    end
+
+    def invalid_code(response)
+      if response.timed_out?
+        raise ClientTimeout
+      elsif response.code.zero?
+        raise ClientError, response.curl_error_message
+      else
+        raise InvalidResponseCode, response.code.to_s
+      end
+    end
+
+  private
+
+    def request(method, urls, opts=nil)
+      opts = options.deep_merge(opts || {})
+      case urls
+      when Array
+        requests = urls.collect do |url|
+          Typhoeus::Request.new url, opts.merge(:method => method)
+        end
+      else
+        Typhoeus::Request.run urls, opts.merge(:method => method)
+      end
+    end
+  end
+end

data/lib/harpy/entry_point.rb

@@ -0,0 +1,35 @@
+require "yajl"
+
+module Harpy
+  class EntryPoint
+    attr_accessor :url
+
+    def initialize(url)
+      self.url = url
+    end
+
+    def resource_url(resource_type)
+      response = Harpy.client.get url
+      case response.code
+      when 200
+        body = Yajl::Parser.parse response.body
+        link = (body["link"] || []).detect{|link| link["rel"] == resource_type}
+        link["href"] if link
+      else
+        Harpy.client.invalid_code response
+      end
+    end
+
+    def urn(urn)
+      response = Harpy.client.get "#{url}/#{urn}"
+      case response.code
+      when 301
+        response.headers_hash["Location"]
+      when 404
+        nil
+      else
+        Harpy.client.invalid_code response
+      end
+    end
+  end
+end

data/lib/harpy/resource.rb

@@ -0,0 +1,197 @@
+require "harpy/client"
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/numeric/bytes"
+require "active_model"
+require "yajl"
+
+module Harpy
+  module Resource
+    extend ActiveSupport::Concern
+
+    included do |base|
+      base.extend ActiveModel::Naming
+      base.send :include, ActiveModel::Conversion
+      base.extend ActiveModel::Translation
+      base.extend ActiveModel::Callbacks
+      base.send :include, ActiveModel::Validations
+      base.send :include, ActiveModel::Validations::Callbacks
+      base.define_model_callbacks :save, :create, :update, :destroy, :only => [:before, :after]
+    end
+
+    def self.from_url(hash)
+      results = {}
+      hash.each do |klass, urls|
+        results[klass] = Harpy.client.get [*urls]
+      end
+      Harpy.client.run results.values.flatten
+      results.each do |klass, requests|
+        requests.collect! do |request|
+          klass.send :from_url_handler, request.response
+        end
+      end
+      results
+    end
+
+    module ClassMethods
+      def from_url(url)
+        case url
+        when Array
+          Harpy.client.run(client.get url).collect{|response| from_url_handler response}
+        else
+          from_url_handler Harpy.client.get url
+        end
+      end
+
+      def from_id(id)
+        url = Harpy.entry_point.urn urn(id)
+        from_url url if url
+      end
+
+      def urn(id)
+        raise NotImplementedError
+      end
+
+      def resource_name
+        name.underscore
+      end
+
+      def search(conditions={})
+        response = Harpy.client.get url, :params => conditions
+        case response.code
+        when 200
+          parsed = Yajl::Parser.parse response.body
+          parsed[resource_name].collect{|model| new model}
+        else
+          Harpy.client.invalid_code response
+        end
+      end
+
+      def with_url(url)
+        raise ArgumentError unless block_given?
+        key = "#{resource_name}_url"
+        old, Thread.current[key] = Thread.current[key], url
+        result = yield
+        Thread.current[key] = old
+        result
+      end
+
+    private
+
+      def url
+        Thread.current["#{resource_name}_url"] || Harpy.entry_point.resource_url(resource_name)
+      end
+
+      def from_url_handler(response)
+        case response.code
+        when 200
+          new Yajl::Parser.parse response.body
+        when 404
+          nil
+        else
+          Harpy.client.invalid_code response
+        end
+      end
+    end
+
+    module InstanceMethods
+      def initialize(attrs = {})
+        @attrs = attrs
+      end
+
+      def attributes=(attrs)
+        @attrs.merge! attrs
+      end
+      
+      def as_json
+        hash = @attrs.dup
+        hash.delete "link"
+        hash.delete "urn"
+        hash
+      end
+
+      def save
+        if valid?
+          _run_save_callbacks do
+            json = Yajl::Encoder.encode as_json
+            raise BodyToBig, "Size: #{json.bytesize} bytes (max 1MB)" if json.bytesize > 1.megabyte
+            persisted? ? update(json) : create(json)
+          end
+        else
+          false
+        end
+      end
+      
+      def link(rel)
+        link = (@attrs["link"]||[]).detect{|l| l["rel"]==rel.to_s}
+        link["href"] if link
+      end
+
+      def url
+        link "self"
+      end
+
+      def url_collection
+        Harpy.entry_point.resource_url self.class.resource_name
+      end
+
+      def id
+        @attrs["urn"].split(":").last if @attrs["urn"]
+      end
+
+      def persisted?
+        @attrs["urn"].present?
+      end
+
+      def inspect
+        "<#{self.class.name} @attrs:#{@attrs.inspect} @errors:#{errors.inspect} persisted:#{persisted?}>"
+      end
+
+      def has_key?(key)
+        @attrs.has_key? key.to_s
+      end
+
+    private
+
+      def create(json)
+        _run_create_callbacks do
+          process_response Harpy.client.post(url_collection, :body => json), :create
+        end
+      end
+
+      def update(json)
+        _run_update_callbacks do
+          raise Harpy::UrlRequired unless url
+          process_response Harpy.client.put(url, :body => json), :update
+        end
+      end
+
+      def process_response(response, context)
+        case response.code
+        when 200, 201, 302
+          @attrs.merge! Yajl::Parser.parse(response.body)
+          true
+        when 204
+          context==:create ? Harpy.client.invalid_code(response) : true
+        when 401
+          raise Harpy::Unauthorized, "Server returned a 401 response code"
+        when 422
+          Yajl::Parser.parse(response.body)["errors"].each do |attr, attr_errors|
+            attr_errors.each{|attr_error| errors[attr] = attr_error }
+          end
+          false
+        else
+          Harpy.client.invalid_code response
+        end
+      end
+
+      def method_missing(method, *args)
+        if persisted? && !@attrs.has_key?(method.to_s)
+          super
+        else
+          @attrs[method.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/harpy/version.rb

@@ -0,0 +1,3 @@
+module Harpy
+  VERSION = "0.1.0"
+end

data/lib/harpy.rb

@@ -0,0 +1,46 @@
+module Harpy
+  class Exception < ::Exception; end
+  class EntryPointRequired < Exception; end
+  class UrlRequired < Exception; end
+  class BodyToBig < Exception; end
+  class ClientTimeout < Exception; end
+  class ClientError < Exception; end
+  class Unauthorized < Exception; end
+  class InvalidResponseCode < Exception; end
+
+  autoload :Client, "harpy/client"
+  autoload :EntryPoint, "harpy/entry_point"
+  autoload :Resource, "harpy/resource"
+  autoload :BodyToBig, "harpy/resource"
+  autoload :UnknownResponseCode, "harpy/resource"
+
+  def self.client=(new_client)
+    @client = new_client
+  end
+
+  def self.client
+    @client ||= Client.new
+  end
+
+  def self.entry_point_url=(url)
+    @entry_point = EntryPoint.new url
+  end
+
+  def self.entry_point_url
+    @entry_point.url if @entry_point
+  end
+
+  def self.entry_point=(value)
+    @entry_point = value
+  end
+
+  def self.entry_point
+    @entry_point || raise(EntryPointRequired, 'you can setup one with Harpy.entry_point_url = "http://localhost"')
+  end
+  
+  def self.reset
+    @client = nil
+    @entry_point = nil
+  end
+
+end

data/spec/harpy/client_spec.rb

@@ -0,0 +1,96 @@
+require "spec_helper"
+
+describe Harpy::Client do
+  let(:entry_url) { "http://localhost" }
+  let(:users_url) { "http://localhost/users" }
+
+  context "by default" do
+    its(:options) { should be_empty }
+  end
+
+  context "initialized with options" do
+    let(:options) { {:username => "harpy", :password => "spec"} }
+    subject { Harpy::Client.new(options) }
+    its(:options) { should == options }
+  end
+
+  [:get, :head, :post, :put, :patch, :delete].each do |method|
+    describe "##{method}(url, opts={})" do
+      context "with one url" do
+        before do
+          @expected = Typhoeus::Response.new :code => 200
+          Typhoeus::Hydra.hydra.stub(method, entry_url).and_return(@expected)
+        end
+        it "sends a #{method.to_s.upcase} to the url" do
+          subject.send(method, entry_url).should == @expected
+        end
+        it "merges options" do
+          client = Harpy::Client.new :headers => {"Authorization" => "spec"}
+          Typhoeus::Hydra.hydra.stub(method, entry_url).and_return(Typhoeus::Response.new :code => 200)
+          response = client.send method, entry_url, :headers => {"X-Files" => "Harpy"}
+          response.request.headers.should include({"X-Files" => "Harpy", "Authorization" => "spec"})
+        end
+      end
+      context "with multiple urls" do
+        it "does not execute requests" do
+          lambda {
+            subject.send method, [entry_url, users_url]
+          }.should_not raise_error Typhoeus::Hydra::NetConnectNotAllowedError
+        end
+        it "returns one requests per url" do
+          requests = subject.send method, [entry_url, users_url]
+          requests.size.should == 2
+          requests.collect(&:method).should =~ [method, method]
+          requests.collect(&:url).should =~ [entry_url, users_url]
+        end
+        it "merges options" do
+          client = Harpy::Client.new :headers => {"Authorization" => "spec"}
+          requests = client.send method, [entry_url, users_url], :headers => {"X-Files" => "Harpy"}
+          requests.each do |request|
+            request.headers.should include({"X-Files" => "Harpy", "Authorization" => "spec"})
+          end
+        end
+      end
+    end
+  end
+  describe "#run(requests)" do
+    before do
+      @entry_response = Typhoeus::Response.new :code => 200, :body => "entry"
+      @users_response = Typhoeus::Response.new :code => 200, :body => "users"
+      
+      Typhoeus::Hydra.hydra.stub(:get, entry_url).and_return @entry_response
+      Typhoeus::Hydra.hydra.stub(:get, users_url).and_return @users_response
+    end
+    it "executes requests in parallel" do
+      Typhoeus::Hydra.hydra.should_receive(:run).once
+      subject.run subject.get([entry_url, users_url])
+    end
+    it "returns responses" do
+      responses = subject.run subject.get([entry_url, users_url])
+      responses.should =~ [@entry_response, @users_response]
+    end
+    it "requests response is filled in" do
+      requests = subject.get([entry_url, users_url])
+      subject.run requests
+      requests[0].response.should == @entry_response
+      requests[1].response.should == @users_response
+    end
+  end
+  describe "#invalid_code(response)" do
+    it "raises Harpy::ClientTimeout on request timeout" do
+      lambda {
+        subject.invalid_code mock("Response", :timed_out? => true)
+      }.should raise_error Harpy::ClientTimeout
+    end
+    it "raises Harpy::ClientError on code 0" do
+      lambda {
+        subject.invalid_code mock("Response", :timed_out? => false, :code => 0, :curl_error_message => "Could not connect to server")
+      }.should raise_error Harpy::ClientError, "Could not connect to server"
+    end
+    it "raises Harpy::InvalidResponseCode with code otherwise" do
+      lambda {
+        subject.invalid_code mock("Response", :timed_out? => false, :code => 404)
+      }.should raise_error Harpy::InvalidResponseCode, "404"
+    end
+  end
+end