nimbu-api 0.0.1

data/lib/nimbu-api/errors.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+module Nimbu
+  module Error
+    class NimbuError < StandardError
+      extend ::Nimbu::Utils::Descendants
+
+      attr_reader :response_message, :response_headers
+
+      # Initialize a new Nimbu error object.
+      #
+      def initialize(message=$!)
+        if message.respond_to?(:backtrace)
+          super(message.message)
+          @response_message = message
+        else
+          super(message.to_s)
+        end
+      end
+
+      def backtrace
+        @response_message ? @response_message.backtrace : super
+      end
+
+    end # NimbuError
+  end # Error
+end # Nimbu
+
+%w( service_error bad_request unauthorized forbidden not_found not_acceptable unprocessable_entity internal_server_error service_unavailable client_error invalid_options required_params unknown_value validations ).each do |error|
+  require "nimbu-api/errors/#{error}"
+end

data/lib/nimbu-api/errors/bad_request.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Nimbu
+  module Error
+    # Raised when Nimbu returns the HTTP status code 400
+    class BadRequest < ServiceError
+      http_status_code 400
+
+      def initialize(response)
+        super(response)
+      end
+    end
+  end
+end # Nimbu

data/lib/nimbu-api/errors/client_error.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 404
+  module Error
+    class ClientError < NimbuError
+      attr_reader :problem, :summary, :resolution
+
+      def initialize(message)
+        super(message)
+      end
+
+      def generate_message(attributes)
+        "\nProblem:\n #{attributes[:problem]}"+
+        "\nSummary:\n #{attributes[:summary]}"+
+        "\nResolution:\n #{attributes[:resolution]}"
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/forbidden.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 403
+  module Error
+    class Forbidden < ServiceError
+      http_status_code 403
+
+      def initialize(response)
+        super(response)
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/internal_server_error.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 500
+  module Error
+    class InternalServerError < ServiceError
+      http_status_code 500
+
+      def initialize(response)
+        super(response)
+      end
+
+    end # InternalServerError
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/invalid_options.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when invalid options are passed to a request body
+  module Error
+    class InvalidOptions < ClientError
+      def initialize(invalid, valid)
+        super(
+          generate_message(
+            :problem => "Invalid option #{invalid.keys.join(', ')} provided for this request.",
+            :summary => "Nimbu gem checks the request parameters passed to ensure that Nimbu api is not hit unnecessairly and to fail fast.",
+            :resolution => "Valid options are: #{valid.join(', ')}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/not_acceptable.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 406
+  module Error
+    class NotAcceptable < ServiceError
+      http_status_code 406
+
+      def initialize(response)
+        super(response)
+      end
+
+    end # NotAcceptable
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/not_found.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 404
+  module Error
+    class NotFound < ServiceError
+      http_status_code 404
+
+      def initialize(env)
+        super(env)
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/required_params.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when invalid options are passed to a request body
+  module Error
+    class RequiredParams < ClientError
+      def initialize(provided, required)
+        super(
+          generate_message(
+            :problem => "Missing required parameters: #{provided.keys.join(', ')} provided for this request.",
+            :summary => "Nimbu gem checks the request parameters passed to ensure that Nimbu api is not hit unnecessairly and to fail fast.",
+            :resolution => "Required parameters are: #{required.join(', ')}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/service_error.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+# require 'multi_json'
+require 'nimbu-api/utils/json'
+
+module Nimbu
+  # Raised when Nimbu returns any of the HTTP status codes
+  module Error
+    class ServiceError < NimbuError
+      include ::Nimbu::Utils::Json
+
+      attr_reader :http_headers
+
+      def initialize(response)
+        @http_headers = response[:response_headers]
+        message = parse_response(response)
+        super(message)
+      end
+
+      def parse_response(response)
+        body = parse_body(response[:body])
+        "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:status]} #{body}"
+      end
+
+      def decode_body(body)
+        if body.respond_to?(:to_str) && body.length >= 2
+           decode body, :symbolize_keys => true
+        else
+          body
+        end
+      end
+
+      def parse_body(body)
+        body = decode_body(body)
+
+        return '' if body.nil? || body.empty?
+
+        if body[:error]
+          body[:error]
+        elsif body[:errors]
+          error = Array(body[:errors]).first
+          if error.kind_of?(Hash)
+            error[:message]
+          else
+            error
+          end
+        elsif body[:message]
+          body[:message]
+        else
+          ''
+        end
+      end
+
+      def self.http_status_code(code)
+        define_method(:http_status_code) { code }
+      end
+
+      def self.errors
+        @errors ||= Hash[
+          descendants.map { |klass| [klass.new({}).http_status_code, klass] }
+        ]
+      end
+
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/service_unavailable.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 503
+  module Error
+    class ServiceUnavailable < ServiceError
+      http_status_code 503
+
+      def initialize(response)
+        super(response)
+      end
+
+    end # ServiceUnavailable
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/unauthorized.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 401
+  module Error
+    class Unauthorized < ServiceError
+      http_status_code 401
+
+      def initialize(response)
+        super(response)
+      end
+
+    end # Unauthorized
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/unknown_value.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when invalid options are passed to a request body
+  module Error
+    class UnknownValue < ClientError
+      def initialize(key, value, permitted)
+        super(
+          generate_message(
+            :problem => "Wrong value of '#{value}' for the parameter: #{key} provided for this request.",
+            :summary => "Nimbu gem checks the request parameters passed to ensure that Nimbu api is not hit unnecessairly and fails fast.",
+            :resolution => "Permitted values are: #{permitted}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/unprocessable_entity.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when Nimbu returns the HTTP status code 422
+  module Error
+    class UnprocessableEntity < ServiceError
+      http_status_code 422
+
+      def initialize(response)
+        super(response)
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/errors/validations.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module Nimbu #:nodoc
+  # Raised when passed parameters are missing or contain wrong values.
+  module Error
+    class Validations < ClientError
+      def initialize(errors)
+        super(
+          generate_message(
+            :problem => "Attempted to send request with nil arguments for #{errors.keys.join(', ')}.",
+            :summary => 'Each request expects certain number of required arguments.',
+            :resolution => 'Double check that the provided arguments are set to some value that is neither nil nor empty string.'
+          )
+        )
+      end
+    end
+  end # Error
+end # Nimbu

data/lib/nimbu-api/pagination.rb

@@ -0,0 +1,106 @@
+# encoding: utf-8
+
+require 'nimbu-api/pagination/paged_request'
+require 'nimbu-api/pagination/page_iterator'
+require 'nimbu-api/pagination/page_links'
+
+module Nimbu
+
+  # A module that decorates response with pagination helpers
+  module Pagination
+    include Nimbu::Utils::Constants
+
+    # Return page links
+    def links
+      @links = Nimbu::Pagination::PageLinks.new(env[:response_headers])
+    end
+
+    # Retrive number of total pages base on current :per_page parameter
+    def count_pages
+      page_iterator.count.to_i
+    end
+
+    # Iterate over results set pages by automatically calling `next_page`
+    # until all pages are exhausted. Caution needs to be exercised when
+    # using this feature - 100 pages iteration will perform 100 API calls.
+    # By default this is off. You can set it on the client, individual API
+    # instances or just per given request.
+    #
+    def auto_paginate(auto=false)
+      if links.any? && (current_api.auto_pagination? || auto)
+        resources_bodies = []
+        each_page { |resource| resources_bodies += resource.body }
+        self.body = resources_bodies
+      end
+      self
+    end
+
+    # Iterator like each for response pages. If there are no pages to
+    # iterate over this method will return current page.
+    def each_page
+      yield self
+      while page_iterator.has_next?
+        yield next_page
+      end
+    end
+
+    # Retrives the result of the first page. Returns <tt>nil</tt> if there is
+    # no first page - either because you are already on the first page
+    # or there are no pages at all in the result.
+    def first_page
+      first_request = page_iterator.first
+      self.instance_eval { @env = first_request.env } if first_request
+      first_request
+    end
+
+    # Retrives the result of the next page. Returns <tt>nil</tt> if there is
+    # no next page or no pages at all.
+    def next_page
+      next_request = page_iterator.next
+      self.instance_eval { @env = next_request.env } if next_request
+      next_request
+    end
+
+    # Retrives the result of the previous page. Returns <tt>nil</tt> if there is
+    # no previous page or no pages at all.
+    def prev_page
+      prev_request = page_iterator.prev
+      self.instance_eval { @env = prev_request.env } if prev_request
+      prev_request
+    end
+    alias :previous_page :prev_page
+
+    # Retrives the result of the last page. Returns <tt>nil</tt> if there is
+    # no last page - either because you are already on the last page,
+    # there is only one page or there are no pages at all in the result.
+    def last_page
+      last_request = page_iterator.last
+      self.instance_eval { @env = last_request.env } if last_request
+      last_request
+    end
+
+    # Retrives a specific result for a page given page number.
+    # The <tt>page_number</tt> parameter is not validate, hitting a page
+    # that does not exist will return Nimbu API error. Consequently, if
+    # there is only one page, this method returns nil
+    def page(page_number)
+      request = page_iterator.get_page(page_number)
+      self.instance_eval { @env = request.env } if request
+      request
+    end
+
+    # Returns <tt>true</tt> if there is another page in the result set,
+    # otherwise <tt>false</tt>
+    def has_next_page?
+      page_iterator.has_next?
+    end
+
+    private
+
+    # Internally used page iterator
+    def page_iterator # :nodoc:
+      @page_iterator = Nimbu::Pagination::PageIterator.new(links, current_api)
+    end
+
+  end # Pagination
+end # Nimbu

data/lib/nimbu-api/pagination/page_iterator.rb

@@ -0,0 +1,157 @@
+# encoding: utf-8
+
+require 'nimbu-api/utils/url'
+require 'uri'
+
+module Nimbu
+  module Pagination
+    class PageIterator
+      include Nimbu::Utils::Constants
+      include Nimbu::Utils::Url
+      include PagedRequest
+
+      # Setup attribute accesor for all the link types
+      ATTRIBUTES = [ META_FIRST, META_NEXT, META_PREV, META_LAST ]
+
+      ATTRIBUTES.each do |attr|
+        attr_accessor :"#{attr}_page_uri", :"#{attr}_page"
+      end
+
+      attr_reader :current_api
+
+      def initialize(links, current_api)
+        @links       = links
+        @current_api = current_api
+        update_page_links @links
+      end
+
+      def has_next?
+        next_page == 0 || !next_page_uri.nil?
+      end
+
+      def count
+        return nil unless last_page_uri
+        parse_query(URI(last_page_uri).query)['page']
+      end
+
+      # Perform http get request for the first resource
+      #
+      def first
+        return nil unless first_page_uri
+        page_uri = URI(first_page_uri)
+        params = parse_query(page_uri.query)
+        if next_page < 1
+          params['sha'] = 'master' if params.keys.include?('sha')
+          params['per_page'] = parse_per_page_number(first_page_uri)
+        else
+          params['page']     = parse_page_number(first_page_uri)
+          params['per_page'] = parse_per_page_number(first_page_uri)
+        end
+
+        response = page_request(page_uri.path, params)
+        update_page_links response.links
+        response
+      end
+
+      # Perform http get request for the next resource
+      #
+      def next
+        return nil unless has_next?
+        page_uri = URI(next_page_uri)
+        params   = parse_query(page_uri.query)
+        if next_page < 1
+          params['sha'] = params['last_sha'] if params.keys.include?('last_sha')
+          params['per_page'] = parse_per_page_number(next_page_uri)
+        else
+          params['page']     = parse_page_number(next_page_uri)
+          params['per_page'] = parse_per_page_number(next_page_uri)
+        end
+
+        response = page_request(page_uri.path, params)
+        update_page_links response.links
+        response
+      end
+
+      # Perform http get request for the previous resource
+      #
+      def prev
+        return nil unless prev_page_uri
+        page_uri = URI(prev_page_uri)
+        params = parse_query(page_uri.query)
+        params['page']     = parse_page_number(prev_page_uri)
+        params['per_page'] = parse_per_page_number(prev_page_uri)
+
+        response = page_request(page_uri.path, params)
+        update_page_links response.links
+        response
+      end
+
+      # Perform http get request for the last resource
+      #
+      def last
+        return nil unless last_page_uri
+        page_uri = URI(last_page_uri)
+        params = parse_query(page_uri.query)
+        params['page']     = parse_page_number(last_page_uri)
+        params['per_page'] = parse_per_page_number(last_page_uri)
+
+        response = page_request(page_uri.path, params)
+        update_page_links response.links
+        response
+      end
+
+      # Returns the result for a specific page.
+      #
+      def get_page(page_number)
+        # Find URI that we can work with, if we cannot get the first or the
+        # last page URI then there is only one page.
+        page_uri = first_page_uri || last_page_uri
+        return nil unless page_uri
+        params = parse_query URI(page_uri).query
+        params['page']     = page_number
+        params['per_page'] = parse_per_page_number(page_uri)
+
+        response = page_request URI(page_uri).path, params
+        update_page_links response.links
+        response
+      end
+
+    private
+
+      def parse_per_page_number(uri) # :nodoc:
+        parse_page_params(uri, PARAM_PER_PAGE)
+      end
+
+      def parse_page_number(uri) # :nodoc:
+        parse_page_params(uri, PARAM_PAGE)
+      end
+
+      # Extracts query string parameter for given name
+      def parse_page_params(uri, attr) # :nodoc:
+        return -1 if uri.nil? || uri.empty?
+        parsed = nil
+        begin
+          parsed = URI.parse(uri)
+        rescue URI::Error => e
+          return -1
+        end
+        param = parse_query_for_param(parsed.query, attr)
+        return -1 if param.nil? || param.empty?
+        begin
+          return param.to_i
+        rescue ArgumentError => err
+          return -1
+        end
+      end
+
+      # Wholesale update of all link attributes
+      def update_page_links(links) # :nodoc:
+        ATTRIBUTES.each do |attr|
+          self.send(:"#{attr}_page_uri=", links.send(:"#{attr}"))
+          self.send(:"#{attr}_page=", parse_page_number(links.send(:"#{attr}")))
+        end
+      end
+
+    end # PageIterator
+  end # Pagination
+end # Nimbu