restify 0.1.0

data/lib/restify/response.rb

@@ -0,0 +1,142 @@
+require 'rack/utils'
+
+module Restify
+  #
+  # A {Response} is returned from an {Adapter} and described
+  # a HTTP response. That includes status code, headers and
+  # body.
+  #
+  # A {Response} is also responsible for decoding its body
+  # according its content type.
+  #
+  class Response
+    #
+    # Map of status symbols to codes. From Rack::Utils.
+    #
+    # @example
+    #   SYMBOL_TO_STATUS_CODE[:ok] #=> 200
+    #
+    SYMBOL_TO_STATUS_CODE = Rack::Utils::SYMBOL_TO_STATUS_CODE
+
+    # Map of status codes to symbols.
+    #
+    # @example
+    #   STATUS_CODE_TO_SYMBOL[200] #=> :ok
+    #
+    STATUS_CODE_TO_SYMBOL = SYMBOL_TO_STATUS_CODE.invert
+
+    # Response body as string.
+    #
+    # @return [String] Response body.
+    #
+    attr_reader :body
+
+    # Response headers as hash.
+    #
+    # @return [Hash<String, String>] Response headers.
+    #
+    attr_reader :headers
+
+    # Response status code.
+    #
+    # @return [Fixnum] Status code.
+    #
+    attr_reader :code
+
+    # Response status symbol.
+    #
+    # @example
+    #   response.status #=> :ok
+    #
+    # @return [Symbol] Status symbol.
+    #
+    attr_reader :status
+
+    # Response status message.
+    #
+    # @return [String] Status message.
+    #
+    attr_reader :message
+
+    # The request that led to this response.
+    #
+    # @return [Request] Request object.
+    #
+    attr_reader :request
+
+    # @api private
+    #
+    def initialize(request, code, headers, body)
+      @request = request
+      @code    = code
+      @status  = STATUS_CODE_TO_SYMBOL[code]
+      @headers = headers
+      @body    = body
+      @message = Rack::Utils::HTTP_STATUS_CODES[code]
+    end
+
+    # Return URL of this response.
+    #
+    def url
+      request.uri
+    end
+
+    # Return list of links from the Link header.
+    #
+    # @return [Array<Link>] Links.
+    #
+    def links
+      @links ||= begin
+        if headers['Link']
+          begin
+            Link.parse(headers['Link'])
+          rescue ArgumentError => e
+            warn e
+            []
+          end
+        else
+          []
+        end
+      end
+    end
+
+    # Return list of relations extracted from links.
+    #
+    # @return [Array<Relation>] Relations.
+    #
+    def relations(client)
+      relations = {}
+      links.each do |link|
+        if (rel = link.metadata['rel'])
+          relations[rel] = Relation.new(client, link.uri)
+        end
+      end
+      relations
+    end
+
+    # Return decoded body according to content type.
+    # Will return `nil` if content cannot be decoded.
+    #
+    # @return [Array, Hash, NilClass] Decoded response body.
+    #
+    def decoded_body
+      @decoded_body ||= begin
+        case headers['Content-Type']
+        when /\Aapplication\/json($|;)/
+          MultiJson.load body
+        else
+          nil
+        end
+      end
+    end
+
+    # Check if response is successful e.g. the status code
+    # is on of 2XX.
+    #
+    # @return [Boolean] True if status code is 2XX otherwise false.
+    #
+    def success?
+      (200...300) === code
+    end
+  end
+end

data/lib/restify/version.rb

@@ -0,0 +1,13 @@
+module Restify
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    STAGE = nil
+    STRING = [MAJOR, MINOR, PATCH, STAGE].reject(&:nil?).join('.').freeze
+
+    def self.to_s
+      STRING
+    end
+  end
+end

data/restify.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'restify/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'restify'
+  spec.version       = Restify::VERSION
+  spec.authors       = ['Jan Graichen']
+  spec.email         = ['jg@altimos.de']
+  spec.summary       = %q{An experimental hypermedia REST client that uses parallel, keep-alive and pipelined requests by default.}
+  spec.description   = %q{An experimental hypermedia REST client that uses parallel, keep-alive and pipelined requests by default.}
+  spec.homepage      = 'https://github.com/jgraichen/restify'
+  spec.license       = 'LGPLv3'
+
+  spec.files         = Dir['**/*'].grep(%r{^((bin|lib|test|spec|features)/|.*\.gemspec|.*LICENSE.*|.*README.*|.*CHANGELOG.*)})
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'obligation', '~> 0.1'
+  spec.add_runtime_dependency 'addressable', '~> 2.3'
+  spec.add_runtime_dependency 'em-http-request', '~> 1.1'
+  spec.add_runtime_dependency 'activesupport', '>= 3.2', '< 5'
+  spec.add_runtime_dependency 'multi_json'
+  spec.add_runtime_dependency 'rack'
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+end

data/spec/restify/link_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe Restify::Link do
+  describe 'class' do
+    describe '#parse' do
+      it 'should parse link with quotes' do
+        links = described_class
+          .parse('<http://example.org/search{?query}>; rel="search"')
+
+        expect(links).to have(1).item
+        expect(links[0].uri.pattern).to eq 'http://example.org/search{?query}'
+        expect(links[0].metadata).to eq 'rel' => 'search'
+      end
+
+      it 'should parse link without quotes' do
+        links = described_class
+          .parse('<http://example.org/search{?query}>; rel=search')
+
+        expect(links).to have(1).item
+        expect(links[0].uri.pattern).to eq 'http://example.org/search{?query}'
+        expect(links[0].metadata).to eq 'rel' => 'search'
+      end
+
+      it 'should parse multiple links' do
+        links = described_class
+          .parse('<p://h.tld/p>; rel=abc, <p://h.tld/b>; a=b; c="d"')
+
+        expect(links).to have(2).item
+        expect(links[0].uri.pattern).to eq 'p://h.tld/p'
+        expect(links[0].metadata).to eq 'rel' => 'abc'
+        expect(links[1].uri.pattern).to eq 'p://h.tld/b'
+        expect(links[1].metadata).to eq 'a' => 'b', 'c' => 'd'
+      end
+
+      it 'should parse link w/o meta' do
+        links = described_class.parse('<p://h.tld/b>')
+
+        expect(links[0].uri.pattern).to eq 'p://h.tld/b'
+      end
+
+      it 'should parse on invalid URI' do
+        links = described_class.parse('<hp://:&*^/fwbhg3>')
+
+        expect(links[0].uri.pattern).to eq 'hp://:&*^/fwbhg3'
+      end
+
+      it 'should error on invalid header' do
+        expect { described_class.parse('</>; rel="s", abc-invalid') }
+          .to raise_error ArgumentError, /Invalid token at \d+:/i
+      end
+    end
+  end
+end

data/spec/restify/resource_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+describe Restify::Resource do
+  let(:client) { double 'client' }
+  let(:relations) { {} }
+  let(:attributes) { {} }
+  let(:res)    { described_class.new(client, relations, attributes) }
+
+  describe '#rel?' do
+    before do
+      res.relations['users']   = true
+      res.relations[:projects] = true
+    end
+
+    it 'should match relations' do
+      expect(res.rel?(:users)).to eq true
+      expect(res.rel?('users')).to eq true
+      expect(res.rel?(:projects)).to eq true
+      expect(res.rel?('projects')).to eq true
+      expect(res.rel?('fuu')).to eq false
+
+      expect(res).to have_rel :users
+      expect(res).to have_rel :projects
+
+      expect(res.relation?(:users)).to eq true
+      expect(res.relation?('users')).to eq true
+      expect(res.relation?(:projects)).to eq true
+      expect(res.relation?('projects')).to eq true
+      expect(res.relation?('fuu')).to eq false
+
+      expect(res).to have_relation :users
+      expect(res).to have_relation :projects
+    end
+  end
+
+  describe '#rel' do
+    let(:users) { double 'users rel' }
+    let(:projects) { double 'projects rel' }
+    before do
+      res.relations['users']   = users
+      res.relations[:projects] = projects
+    end
+
+    it 'should return relation' do
+      expect(res.rel(:users)).to eq users
+      expect(res.rel('users')).to eq users
+      expect(res.rel(:projects)).to eq projects
+      expect(res.rel('projects')).to eq projects
+      expect { res.rel(:fuu) }.to raise_error KeyError
+
+      expect(res.relation(:users)).to eq users
+      expect(res.relation('users')).to eq users
+      expect(res.relation(:projects)).to eq projects
+      expect(res.relation('projects')).to eq projects
+      expect { res.relation(:fuu) }.to raise_error KeyError
+    end
+  end
+
+  describe '#key?' do
+    let(:attributes) { {a: 0, 'b' => 1, 0 => 2} }
+
+    it 'should test for key inclusion' do
+      expect(res.key?(:a)).to eq true
+      expect(res.key?(:b)).to eq true
+      expect(res.key?('a')).to eq true
+      expect(res.key?('b')).to eq true
+      expect(res.key?(0)).to eq true
+
+      expect(res.key?(:c)).to eq false
+      expect(res.key?('d')).to eq false
+
+      expect(res).to have_key :a
+      expect(res).to have_key :b
+      expect(res).to have_key 'a'
+      expect(res).to have_key 'b'
+      expect(res).to have_key 0
+
+      expect(res).to_not have_key :c
+      expect(res).to_not have_key 'd'
+    end
+  end
+
+  describe '#each' do
+    let(:attributes) { {a: 0, b: 1} }
+
+    it 'should yield' do
+      expect { |cb| res.each(&cb) }.to yield_control.twice
+      expect { |cb| res.each(&cb) }.to yield_successive_args ['a', 0], ['b', 1]
+    end
+
+    it 'should return enumerator' do
+      expect(res.each).to be_a Enumerator
+      expect(res.each.to_a).to eq [['a', 0], ['b', 1]]
+    end
+  end
+end

data/spec/restify_spec.rb

@@ -0,0 +1,219 @@
+require 'spec_helper'
+
+describe Restify do
+  context 'as a dynamic HATEOAS client' do
+    before do
+      stub_request(:get, 'http://localhost/base').to_return do
+        <<-EOF.gsub(/^ {10}/, '')
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          Transfer-Encoding: chunked
+          Link: <http://localhost/base/users{/id}>; rel="users"
+          Link: <http://localhost/base/courses{/id}>; rel="courses"
+
+          {
+            "profile_url": "http://localhost/base/profile",
+            "search_url": "http://localhost/base/search?q={query}",
+            "mirror_url": null
+          }
+        EOF
+      end
+
+      stub_request(:get, 'http://localhost/base/users').to_return do
+        <<-EOF.gsub(/^ {10}/, '')
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          Transfer-Encoding: chunked
+
+          [{
+             "name": "John Smith",
+             "url": "http://localhost/base/users/john.smith",
+             "blurb_url": "http://localhost/base/users/john.smith/blurb"
+           },
+           {
+             "name": "Jane Smith",
+             "self_url": "http://localhost/base/user/jane.smith"
+           }]
+        EOF
+      end
+
+      stub_request(:post, 'http://localhost/base/users')
+        .with(body: {})
+        .to_return do
+          <<-EOF.gsub(/^ {12}/, '')
+            HTTP/1.1 422 Unprocessable Entity
+            Content-Type: application/json
+            Transfer-Encoding: chunked
+
+            {"errors":{"name":["can't be blank"]}}
+          EOF
+      end
+
+      stub_request(:post, 'http://localhost/base/users')
+        .with(body: {name: 'John Smith'})
+        .to_return do
+          <<-EOF.gsub(/^ {12}/, '')
+            HTTP/1.1 201 Created
+            Content-Type: application/json
+            Location: http://localhost/base/users/john.smith
+            Transfer-Encoding: chunked
+
+            {
+              "name": "John Smith",
+              "url": "http://localhost/base/users/john.smith",
+              "blurb_url": "http://localhost/base/users/john.smith/blurb"
+            }
+          EOF
+      end
+
+      stub_request(:get, 'http://localhost/base/users/john.smith')
+        .to_return do <<-EOF.gsub(/^ {10}/, '')
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          Link: <http://localhost/base/users/john.smith>; rel="self"
+          Transfer-Encoding: chunked
+
+          {
+            "name": "John Smith",
+            "url": "http://localhost/base/users/john.smith"
+          }
+        EOF
+      end
+
+      stub_request(:get, 'http://localhost/base/users/john.smith/blurb')
+        .to_return do <<-EOF.gsub(/^ {10}/, '')
+          HTTP/1.1 200 OK
+          Content-Type: application/json
+          Link: <http://localhost/base/users/john.smith>; rel="user"
+          Transfer-Encoding: chunked
+
+          {
+            "title": "Prof. Dr. John Smith",
+            "image": "http://example.org/avatar.png"
+          }
+        EOF
+      end
+    end
+
+    let(:c) do
+      Restify.new('http://localhost/base').value
+    end
+
+    context 'within threads' do
+      it 'should consume the API' do
+        # Let's get all users
+
+        # Therefore we need the `users` relations of our root
+        # resource.
+        users_relation = c.rel(:users)
+
+        # The relation is a `Restify::Relation` and provides
+        # method to enqueue e.g. GET or POST requests with
+        # parameters to fill in possible URI template placeholders.
+        expect(users_relation).to be_a Restify::Relation
+
+        # Let's create a user first.
+        # This method returns instantly and returns an `Obligation`.
+        # This `Obligation` represents the future value.
+        # We can pass parameters to a request. They will be used
+        # to expand the URI template behind the relation. Additional
+        # fields will be encoding in e.g. JSON and send if not a GET
+        # request.
+        create_user_promise = users_relation.post
+        expect(create_user_promise).to be_a Obligation
+
+        # We can do other things while the request is processed in
+        # the background. When we need the response with can call
+        # {#value} on the promise that will block the thread until
+        # the result is here.
+        begin
+          create_user_promise.value
+        rescue Restify::ClientError => e
+          # Because we forgot to send a "name" the server complains
+          # with an error code that will lead to a raised error.
+
+          expect(e.status).to eq :unprocessable_entity
+          expect(e.code).to eq 422
+          expect(e.errors).to eq 'name' => ["can't be blank"]
+        end
+
+        # Let's try again.
+        created_user = users_relation.post(name: 'John Smith').value
+
+        # The server returns a 201 Created response with the created
+        # resource.
+        expect(created_user.status).to eq :created
+        expect(created_user.code).to eq 201
+
+        expect(created_user).to have_key :name
+        expect(created_user[:name]).to eq 'John Smith'
+
+        # Let's follow the "Location" header.
+        followed_resource = created_user.follow.value
+
+        expect(followed_resource.status).to eq :ok
+        expect(followed_resource.code).to eq 200
+
+        expect(followed_resource).to have_key :name
+        expect(followed_resource[:name]).to eq 'John Smith'
+
+        # Now we will fetch a list of all users.
+        users = users_relation.get.value
+
+        # We get a collection back (Restify::Collection).
+        expect(users).to have(2).items
+
+        # Let's get the first one.
+        user = users.first
+
+        # We have all our attributes and relations here as defined in the
+        # responses from the server.
+        expect(user).to have_key :name
+        expect(user[:name]).to eq 'John Smith'
+        expect(user).to have_relation :self
+        expect(user).to have_relation :blurb
+
+        # Let's get the blurb.
+        blurb = user.rel(:blurb).get.value
+
+        expect(blurb).to have_key :title
+        expect(blurb).to have_key :image
+
+        expect(blurb[:title]).to eq 'Prof. Dr. John Smith'
+        expect(blurb[:image]).to eq 'http://example.org/avatar.png'
+      end
+    end
+
+    context 'within eventmachine' do
+      it 'should consume the API' do
+        pending
+
+        EventMachine.run do
+          users_promise = c.rel(:users).get
+          users_promise.then do |users|
+            expect(users).to have(2).items
+
+            user = users.first
+            expect(user).to have_key :name
+            expect(user[:name]).to eq 'John Smith'
+            expect(user).to have_relation :self
+            expect(user).to have_relation :blurb
+
+            user.rel(:blurb).get.then do |blurb|
+              expect(blurb).to have_key :title
+              expect(blurb).to have_key :image
+
+              expect(blurb[:title]).to eq 'Prof. Dr. John Smith'
+              expect(blurb[:image]).to eq 'http://example.org/avatar.png'
+
+              EventMachine.stop
+              @done = true
+            end
+          end
+        end
+
+        expect(@done).to be true
+      end
+    end
+  end
+end