restify 0.1.0

data/lib/restify/client.rb

@@ -0,0 +1,106 @@
+module Restify
+  #
+  # A {ResponseError} is returned on a non-successful
+  # response from server. Usually it will either be a
+  # {ClientError} or a {ServerError}.
+  #
+  class ResponseError < StandardError
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super "#{response.message} (#{response.code}) for `#{response.url}':\n" \
+            "  #{errors.inspect}"
+    end
+
+    # Return response status.
+    #
+    # @return [Symbol] Response status.
+    # @see Response#status
+    #
+    def status
+      response.status
+    end
+
+    # Return response status code.
+    #
+    # @return [Fixnum] Response status code.
+    # @see Response#code
+    #
+    def code
+      response.code
+    end
+
+    # Return hash or array of errors if response included
+    # such a thing otherwise it returns nil.
+    #
+    def errors
+      response.decoded_body['errors'] || response.decoded_body[:errors]
+    end
+  end
+
+  # A {ClientError} will be raised when a response has a
+  # 4XX status code.
+  class ClientError < ResponseError; end
+
+  # A {ServerError} will be raised when a response has a
+  # 5XX status code.
+  class ServerError < ResponseError; end
+
+  # @api private
+  #
+  class Client
+    #
+    # Keys that should not be extracted from options
+    # to expand URI templates.
+    RESERVED_KEYS = [:data]
+
+    # @api private
+    #
+    # Request given path with given method.
+    #
+    # Returns an obligation that will return a collection or
+    # resource or fail with a response error depending on
+    # response from server.
+    #
+    def request(method, path, opts = {})
+      data    = opts.fetch(:data, opts)
+      request = Request.new method: method, uri: base.join(path.to_s), data: data
+
+      ::Restify.adapter.call(request).then do |response|
+        if response.success?
+          handle_success response
+        else
+          handle_error response
+        end
+      end
+    end
+
+    private
+
+    attr_reader :base
+
+    def initialize(uri)
+      @base = ::Addressable::URI.parse(uri)
+    end
+
+    def handle_success(response)
+      if response.decoded_body.is_a?(Array)
+        Collection.create(self, response.decoded_body, response)
+      else
+        Resource.create(self, response.decoded_body, response)
+      end
+    end
+
+    def handle_error(response)
+      case response.code
+      when 400...500
+        raise ClientError.new(response)
+      when 500...600
+        raise ServerError.new(response)
+      else
+        raise RuntimeError.new "Unknown response code: #{response.code}"
+      end
+    end
+  end
+end

data/lib/restify/collection.rb

@@ -0,0 +1,69 @@
+module Restify
+  #
+  class Collection
+    include Relations
+
+    # @!method [](index)
+    #   Retrieve value for given index.
+    #
+    #   @param index [Integer] Index.
+    #   @return [Object] Data value for given index.
+    #
+    delegate :[], to: :items
+
+    # @!method size
+    #   Return size of collection. Only includes size of current
+    #   page in paginated resources.
+    #
+    #   @return [Integer] Number of items in current collection.
+    #
+    delegate :size, to: :items
+
+    # @!method first
+    #   Return first item of collection.
+    #
+    #   @return [Resource, Collection, Object] Return first
+    #
+    delegate :first, to: :items
+
+    # @!method each
+    #   Iterate over all items or return enumerator.
+    #
+    #   @overload each
+    #     Calls block once for each item, passing the item as
+    #     parameters.
+    #
+    #     @yield [item] Yield for each item.
+    #     @yieldparam item [Resource, Collection, Object] Collection item.
+    #
+    #   @overload each
+    #     Return enumerator for each item.
+    #
+    #     @return [Enumerator] Enumerator for each item.
+    #
+    delegate :each, to: :items
+
+    # Return parsed resource attributes as hash.
+    #
+    # @return [Array] Collection items.
+    #
+    def items
+      @items ||= []
+    end
+
+    def initialize(client, relations = {}, items = [])
+      @client     = client
+      @relations  = HashWithIndifferentAccess.new relations
+      @items      = Array items
+    end
+
+    class << self
+      def create(client, data, response)
+        data      = data.map { |s| Resource.create(client, s, nil) } if data
+        relations = response ? response.relations(client) : nil
+
+        new client, relations, data
+      end
+    end
+  end
+end

data/lib/restify/link.rb

@@ -0,0 +1,100 @@
+module Restify
+  #
+  # A {Link} represents a single entry from the Link header
+  # of a HTTP response.
+  #
+  class Link
+    #
+    # URI of the link interpreted as a RFC6570 template.
+    #
+    # @return [Addressable::Template] URI template.
+    #
+    attr_reader :uri
+
+    # Link metadata like "rel" if specified.
+    #
+    # @return [HashWithIndifferentAccess<String, String>] Metadata.
+    #
+    attr_reader :metadata
+
+    def initialize(uri, metadata = {})
+      @uri      = uri
+      @metadata = HashWithIndifferentAccess.new(metadata)
+    end
+
+    class << self
+      REGEXP_URI = /<[^>]*>\s*/
+      REGEXP_PAR = /;\s*\w+\s*=\s*/i
+      REGEXP_QUT = /"[^"]*"\s*/
+      REGEXP_ARG = /\w+\s*/i
+
+      def parse(string)
+        scanner = StringScanner.new(string.strip)
+
+        catch(:invalid) do
+          return parse_links(scanner)
+        end
+
+        fail ArgumentError,
+             "Invalid token at #{scanner.pos}: '#{scanner.rest}'"
+      end
+
+      private
+
+      def parse_links(scanner)
+        links = []
+        loop do
+          if (link = parse_link(scanner))
+            links << link
+          elsif scanner.eos?
+            return links
+          else
+            throw :invalid
+          end
+        end
+      end
+
+      def parse_link(scanner)
+        if (m = scanner.scan(REGEXP_URI))
+          uri    = Addressable::Template.new(m.strip[1..-2])
+          params = parse_params(scanner)
+          new uri, params
+        else
+          false
+        end
+      end
+
+      def parse_params(scanner)
+        params = {}
+        loop do
+          if (p = parse_param(scanner))
+            params[p[0]] = p[1]
+          elsif scanner.scan(/,\s*/) || scanner.eos?
+            return params
+          else
+            throw :invalid
+          end
+        end
+      end
+
+      def parse_param(scanner)
+        if (m = scanner.scan(REGEXP_PAR))
+          key = m.strip[1..-2].strip
+          [key, parse_value(scanner)]
+        else
+          false
+        end
+      end
+
+      def parse_value(scanner)
+        if (m = scanner.scan(REGEXP_QUT))
+          m.strip[1..-2]
+        elsif (m = scanner.scan(REGEXP_ARG))
+          m.strip
+        else
+          throw :invalid
+        end
+      end
+    end
+  end
+end

data/lib/restify/parser/json.rb

@@ -0,0 +1,16 @@
+module Restify
+  #
+  module Processors
+    #
+    # Decode JSON responses.
+    class JSON
+      def parse(str)
+        MultiJSON.load(str)
+      end
+
+      def format
+        :json
+      end
+    end
+  end
+end

data/lib/restify/relation.rb

@@ -0,0 +1,33 @@
+module Restify
+  #
+  class Relation
+    def initialize(client, uri_template)
+      @client   = client
+      @template = if uri_template.is_a?(Addressable::Template)
+                    uri_template
+                  else
+                    Addressable::Template.new(uri_template)
+                  end
+    end
+
+    def get(opts = {})
+      request :get, opts
+    end
+
+    def post(opts = {})
+      request :post, opts
+    end
+
+    private
+
+    attr_reader :client, :template
+
+    def request(method, opts = {})
+      keys   = template.variables - Client::RESERVED_KEYS
+      params = opts.except!(keys)
+      uri    = template.expand(params)
+
+      client.request method, uri, opts
+    end
+  end
+end

data/lib/restify/relations.rb

@@ -0,0 +1,35 @@
+module Restify
+  #
+  module Relations
+    #
+    # Check if resource has a relation with given name.
+    #
+    # @param name [String, Symbol] Relation name.
+    # @return [Boolean] True if resource has relation, false otherwise.
+    #
+    def rel?(name)
+      relations.key? name
+    end
+    alias_method :relation?, :rel?
+    alias_method :has_rel?, :rel?
+    alias_method :has_relation?, :rel?
+
+    # Return relation with given name.
+    #
+    # @param name [String, Symbol] Relation name.
+    # @return [Relation] Relation.
+    #
+    def rel(name)
+      relations.fetch name
+    end
+    alias_method :relation, :rel
+
+    # Hash of all known relations.
+    #
+    # @return [HashWithIndifferentAccess<String, Relation>] Relations.
+    #
+    def relations
+      @relations ||= HashWithIndifferentAccess.new
+    end
+  end
+end

data/lib/restify/request.rb

@@ -0,0 +1,37 @@
+module Restify
+  #
+  class Request
+    #
+    # HTTP method.
+    #
+    # @return [String] HTTP method.
+    #
+    attr_reader :method
+
+    # Request URI.
+    #
+    # @return [String] Request URI.
+    #
+    attr_reader :uri
+
+    # Request data.
+    #
+    attr_reader :data
+
+    def initialize(opts = {})
+      @method = opts.fetch(:method, :get)
+      @uri    = opts.fetch(:uri) { fail ArgumentError, ':uri required.' }
+      @data   = opts.fetch(:data, nil)
+    end
+
+    def body
+      @body ||= MultiJson.dump(data)
+    end
+
+    def headers
+      {
+        'Content-Type' => 'application/json'
+      }
+    end
+  end
+end

data/lib/restify/resource.rb

@@ -0,0 +1,131 @@
+module Restify
+  #
+  class Resource
+    include Relations
+
+    # Return content Media-Type.
+    #
+    # @return [MediaType] Resource media type.
+    #
+    attr_reader :media_type
+
+    # @!method [](key)
+    #   Retrieve value for given key.
+    #
+    #   @param key [String, Symbol] Data key.
+    #   @return [Object] Data value for given key.
+    #
+    delegate :[], to: :attributes
+
+    # @!method key?(name)
+    #   Check if resource has given key.
+    #
+    #   @param name [String, Symbol] Key name.
+    #   @return [Boolean] True if resource contains key, false otherwise.
+    #
+    delegate :key?, :has_key?, to: :attributes
+
+    # @!method each
+    #   Iterate over keys and values or return enumerator.
+    #
+    #   @overload each
+    #     Calls block once for each key, passing the key-value pair as
+    #     parameters.
+    #
+    #     @yield [key, value] Yield for each key-value pair.
+    #     @yieldparam key [String] Attribute key.
+    #     @yieldparam value [Object] Attribute value.
+    #
+    #   @overload each
+    #     Return enumerator for each key-value pair.
+    #
+    #     @return [Enumerator] Enumerator for each key-value pair.
+    #
+    delegate :each, to: :attributes
+
+    # Return parsed resource attributes as hash.
+    #
+    # @return [HashWithIndifferentAccess] Attribute hash.
+    #
+    def attributes
+      @attributes ||= HashWithIndifferentAccess.new
+    end
+
+    # @!method status
+    #   Return response status if available.
+    #
+    #   @return [Symbol] Response status.
+    #   @see Response#status
+    #
+    delegate :status, to: :@response, allow_nil: true
+
+    # @!method code
+    #   Return response status code if available.
+    #
+    #   @return [Fixnum] Response status code.
+    #   @see Response#code
+    #
+    delegate :code, to: :@response, allow_nil: true
+
+    # Follow the Location header from the response of
+    # this resource if available.
+    #
+    # @return [Obligation<Resource>] Followed resource.
+    #
+    def follow
+      if @response && @response.headers['LOCATION']
+        @client.request :get, @response.headers['LOCATION']
+      else
+        raise RuntimeError.new 'Nothing to follow.'
+      end
+    end
+
+    def initialize(client, relations = {}, attributes = {}, response = nil)
+      @client     = client
+      @response   = response
+      @relations  = HashWithIndifferentAccess.new relations
+      @attributes = HashWithIndifferentAccess.new attributes
+    end
+
+    class << self
+      #
+      # Build a resource from given response.
+      #
+      def create(client, data, response)
+        relations = {}
+        relations = response.relations(client) if response
+
+        hash = {}
+        if data
+          data.each do |key, value|
+            hash[key] = case value
+                        when Array
+                          Collection.create(client, value, nil)
+                        when Hash
+                          Resource.create(client, value, nil)
+                        else
+                          value
+                        end
+          end
+
+          data.keys.each do |key|
+            name = nil
+            if (m = /\A(\w+)_url\z/.match(key))
+              name = m[1]
+            elsif key == 'url'
+              name = :self
+            else
+              next
+            end
+
+            unless relations.key?(name) || data[key].to_s.blank?
+              relations[name] = Relation.new(client, data[key].to_s)
+            end
+          end
+        end
+
+        new client, relations, hash, response
+      end
+    end
+  end
+end