github_api2 1.0.0

data/lib/github_api2/connection.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+
+require 'faraday'
+
+require_relative 'constants'
+
+module Github
+  # Specifies Http connection options
+  module Connection
+    extend self
+    include Github::Constants
+
+    ALLOWED_OPTIONS = [
+      :headers,
+      :url,
+      :params,
+      :request,
+      :ssl
+    ].freeze
+
+    # Default requets header information
+    #
+    # @return [Hash[String]]
+    #
+    # @api private
+    def default_headers
+      {
+        ACCEPT         => 'application/vnd.github.v3+json,' \
+                          'application/vnd.github.beta+json;q=0.5,' \
+                          'application/json;q=0.1',
+        ACCEPT_CHARSET => 'utf-8'
+      }
+    end
+
+    # Create default connection options
+    #
+    # @return [Hash[Symbol]]
+    #   the default options
+    #
+    # @api private
+    def default_options(options = {})
+      headers = default_headers.merge(options[:headers] || {})
+      headers.merge!({USER_AGENT => options[:user_agent]})
+      {
+        headers: headers,
+        ssl: options[:ssl],
+        url: options[:endpoint]
+      }
+    end
+
+    # Exposes middleware builder to facilitate custom stacks and easy
+    # addition of new extensions such as cache adapter.
+    #
+    # @api public
+    def stack(options = {})
+      @stack ||= begin
+        builder_class = if defined?(Faraday::RackBuilder)
+                          Faraday::RackBuilder
+                        else
+                          Faraday::Builder
+                        end
+        builder_class.new(&Github.default_middleware(options))
+      end
+    end
+
+    # Creates http connection
+    #
+    # Returns a Faraday::Connection object
+    def connection(api, options = {})
+      connection_options = default_options(options)
+      connection_options.merge!(builder: stack(options.merge!(api: api)))
+      if options[:connection_options]
+        connection_options.deep_merge!(options[:connection_options])
+      end
+      if ENV['DEBUG']
+        p "Connection options : \n"
+        pp connection_options
+      end
+      Faraday.new(connection_options)
+    end
+  end # Connection
+end # Github

data/lib/github_api2/constants.rb

@@ -0,0 +1,61 @@
+module Github
+  module Constants
+    extend self
+
+    # Response headers
+    RATELIMIT_REMAINING = 'X-RateLimit-Remaining'.freeze
+
+    RATELIMIT_LIMIT = 'X-RateLimit-Limit'.freeze
+
+    RATELIMIT_RESET = 'X-RateLimit-Reset'.freeze
+
+    CONTENT_TYPE = 'Content-Type'.freeze
+
+    CONTENT_LENGTH = 'content-length'.freeze
+
+    CACHE_CONTROL = 'cache-control'.freeze
+
+    ETAG = 'ETag'.freeze
+
+    SERVER = 'Server'.freeze
+
+    DATE = 'Date'.freeze
+
+    LOCATION = 'Location'.freeze
+
+    USER_AGENT = 'User-Agent'.freeze
+
+    ACCEPT = 'Accept'.freeze
+
+    ACCEPT_CHARSET = 'Accept-Charset'.freeze
+
+    OAUTH_SCOPES = 'X-OAuth-Scopes'.freeze
+
+    ACCEPTED_OAUTH_SCOPES = 'X-Accepted-Oauth-Scopes'.freeze
+
+    # Link headers
+    HEADER_LINK = "Link".freeze
+
+    HEADER_NEXT = "X-Next".freeze
+
+    HEADER_LAST = "X-Last".freeze
+
+    META_REL = "rel".freeze
+
+    META_LAST = "last".freeze
+
+    META_NEXT = "next".freeze
+
+    META_FIRST = "first".freeze
+
+    META_PREV = "prev".freeze
+
+    PARAM_PAGE = "page".freeze
+
+    PARAM_PER_PAGE = "per_page".freeze
+
+    PARAM_START_PAGE = "start_page".freeze
+
+
+  end # Constants
+end # Github

data/lib/github_api2/core_ext/array.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+class Array # :nodoc:
+
+  # Returns a new arrray with keys removed
+  #
+  def except(*keys)
+    self.dup.except!(*keys)
+  end unless method_defined? :except
+
+  # Similar to except but modifies self
+  #
+  def except!(*items)
+    copy = self.dup
+    copy.reject! { |item| items.include? item }
+    copy
+  end unless method_defined? :except!
+
+  # Selects a hash from the arguments list
+  #
+  def extract_options!
+    last.is_a?(::Hash) ? pop : {}
+  end unless method_defined? :extract_options!
+
+end # Array

data/lib/github_api2/core_ext/hash.rb

@@ -0,0 +1,91 @@
+# encoding: utf-8
+
+class Hash # :nodoc:
+
+  # Returns a new hash with keys removed
+  #
+  def except(*items)
+    self.dup.except!(*items)
+  end unless method_defined? :except
+
+  # Similar to except but modifies self
+  #
+  def except!(*keys)
+    keys.each { |key| delete(key) }
+    self
+  end unless method_defined? :except!
+
+  # Returns a new hash with all the keys converted to symbols
+  #
+  def symbolize_keys
+    inject({}) do |hash, (key, value)|
+      hash[(key.to_sym rescue key) || key] = value
+      hash
+    end
+  end unless method_defined? :symbolize_keys
+
+  # Similar to symbolize_keys but modifies self
+  #
+  def symbolize_keys!
+    hash = symbolize_keys
+    hash.each do |key, val|
+      hash[key] = case val
+        when Hash
+          val.symbolize_keys!
+        when Array
+          val.map do |item|
+            item.is_a?(Hash) ? item.symbolize_keys! : item
+          end
+        else
+          val
+        end
+    end
+    return hash
+  end unless method_defined? :symbolize_keys!
+
+  # Returns hash collapsed into a query string
+  #
+  def serialize
+    self.map { |key, val| [key, val].join("=") }.join("&")
+  end unless method_defined? :serialize
+
+  # Searches for all deeply nested keys
+  #
+  def deep_keys
+    keys = self.keys
+    keys.each do |key|
+      if self[key].is_a?(Hash)
+        keys << self[key].deep_keys.compact.flatten
+        next
+      end
+    end
+    keys.flatten
+  end unless method_defined? :deep_keys
+
+  # Returns true if the given key is present inside deeply nested hash
+  #
+  def deep_key?(key)
+    self.deep_keys.include? key
+  end unless method_defined? :deep_key?
+
+  # Recursively merges self with other hash and returns new hash.
+  #
+  def deep_merge(other, &block)
+    dup.deep_merge!(other, &block)
+  end unless method_defined? :deep_merge
+
+  # Similar as deep_merge but modifies self
+  #
+  def deep_merge!(other, &block)
+    other.each_pair do |key, val|
+      tval = self[key]
+      if tval.is_a?(Hash) && val.is_a?(Hash)
+        self[key] = tval.deep_merge(val)
+      else
+        self[key] = block && tval ? block.call(k, tval, val) : val
+      end
+    end
+    self
+  end unless method_defined? :deep_merge!
+
+end # Hash

data/lib/github_api2/deprecation.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+module Github
+
+  DEPRECATION_PREFIX = "[GithubAPI] Deprecation warning:"
+
+  class << self
+
+    attr_writer :deprecation_tracker
+
+    def deprecation_tracker
+      @deprecation_tracker ||= []
+    end
+
+    # Displays deprecation message to the user.
+    # Each message is printed once.
+    def deprecate(method, alternate_method=nil)
+      return if deprecation_tracker.include? method
+      deprecation_tracker << method
+
+      message = <<-NOTICE
+#{DEPRECATION_PREFIX}
+
+* #{method} is deprecated.
+NOTICE
+      if alternate_method
+        message << <<-ADDITIONAL
+* please use #{alternate_method} instead.
+ADDITIONAL
+      end
+      warn_deprecation(message)
+    end
+
+    def warn_deprecation(message)
+      send :warn, message
+    end
+  end
+
+end # Github

data/lib/github_api2/error/client_error.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+
+require_relative '../error'
+
+module Github #:nodoc
+  # Raised when Github returns the HTTP status code 404
+  module Error
+    class ClientError < GithubError
+      attr_reader :problem, :summary, :resolution
+
+      def initialize(message)
+        super(message)
+      end
+
+      def generate_message(attributes)
+        @problem = attributes[:problem]
+        @summary = attributes[:summary]
+        @resolution = attributes[:resolution]
+        "\nProblem:\n #{@problem}"+
+        "\nSummary:\n #{@summary}"+
+        "\nResolution:\n #{@resolution}"
+      end
+    end
+
+    # Raised when invalid options are passed to a request body
+    class InvalidOptions < ClientError
+      def initialize(invalid, valid)
+        super(
+          generate_message(
+            problem: "Invalid option #{invalid.keys.join(', ')} provided for this request.",
+            summary: "Github gem checks the request parameters passed to ensure that github api is not hit unnecessarily and to fail fast.",
+            resolution: "Valid options are: #{valid.join(', ')}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+
+    # Raised when invalid options are passed to a request body
+    class RequiredParams < ClientError
+      def initialize(provided, required)
+        super(
+          generate_message(
+            problem: "Missing required parameters: #{provided.keys.join(', ')} provided for this request.",
+            summary: "Github gem checks the request parameters passed to ensure that github api is not hit unnecessarily and to fail fast.",
+            resolution: "Required parameters are: #{required.join(', ')}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+
+    # Raised when invalid options are passed to a request body
+    class UnknownMedia < ClientError
+      def initialize(file)
+        super(
+          generate_message(
+            problem: "Unknown content type for: '#{file}' provided for this request.",
+            summary: "Github gem infers the content type of the resource by calling the mime-types gem type inference.",
+            resolution: "Please install mime-types gem to infer the resource content type."
+          )
+        )
+      end
+    end
+
+    # Raised when invalid options are passed to a request body
+    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: "Github gem checks the request parameters passed to ensure that github api is not hit unnecessairly and fails fast.",
+            resolution: "Permitted values are: #{permitted}, make sure these are the ones you are using"
+          )
+        )
+      end
+    end
+
+    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 # Github

data/lib/github_api2/error/service_error.rb

@@ -0,0 +1,223 @@
+# encoding: utf-8
+
+require 'json'
+
+require_relative '../error'
+
+module Github
+  # Raised when GitHub returns any of the HTTP status codes
+  module Error
+    class ServiceError < GithubError
+      # Add http status code method to error type
+      #
+      # @param [Integer] code
+      #   the status code
+      #
+      # @api public
+      def self.http_status_code(code)
+        define_method(:http_status_code) { code }
+      end
+
+      # A mapping of status codes and error types
+      #
+      # @return [Hash[Integer, Object]]
+      #
+      # @api public
+      def self.error_mapping
+        @error_mapping ||= Hash[
+          descendants.map do |klass|
+            [klass.new({}).http_status_code, klass]
+          end
+        ]
+      end
+
+      MIN_BODY_LENGTH = 2
+
+      # Create a ServiceError
+      #
+      # @param [Hash[Symbol]] response
+      #
+      # @api public
+      def initialize(response)
+        @headers = response[:response_headers]
+        @body    = response[:body]
+        @status  = response[:status]
+
+        @response_headers = @headers
+        @response_message = @body
+
+        super(create_message(response))
+      end
+
+      # Expose response payload as JSON object if possible
+      #
+      # @return [Hash[Symbol]|String]
+      #
+      # @api public
+      def data
+        @data ||= decode_data(@body)
+      end
+
+      # Stores error message(s) returned in response body
+      #
+      # @return [Array[Hash[Symbol]]]
+      #   the array of hash error objects
+      #
+      # @api public
+      def error_messages
+        @error_messages ||= begin
+          data[:errors] ? data[:errors] : [data]
+        end
+      end
+
+      private
+
+      # Create full error message
+      #
+      # @param [Hash[Symbol]] response
+      #   the http response
+      #
+      # @return [String]
+      #   the error message
+      #
+      # @api private
+      def create_message(response)
+        return if response.nil?
+
+        message = "#{response[:method].to_s.upcase} "
+        message << "#{response[:url]}: "
+        message << "#{@status} - #{format_response}"
+        message
+      end
+
+      # Decode body information if in JSON format
+      #
+      # @param [String] body
+      #   the response body
+      #
+      # @api private
+      def decode_data(body)
+        if body.respond_to?(:to_str) &&
+           body.length >= MIN_BODY_LENGTH &&
+           @headers[:content_type] =~ /json/
+
+          JSON.parse(body, symbolize_names: true)
+        else
+          body
+        end
+      end
+
+      # Read response body and convert to human friendly format
+      #
+      # @return [String]
+      #
+      # @api private
+      def format_response
+        return '' if data.nil? || data.empty?
+
+        case data
+        when Hash
+          message = data[:message] ? data[:message] : ' '
+          docs = data[:documentation_url]
+          error = create_error_summary
+          message << error if error
+          message << "\nSee: #{docs}" if docs
+          message
+        when String
+          data
+        end
+      end
+
+      # Create error summary from response body
+      #
+      # @return [String]
+      #
+      # @api private
+      def create_error_summary
+        if data[:error]
+          "\nError: #{data[:error]}"
+        elsif data[:errors]
+          message = "\nErrors:\n"
+          message << data[:errors].map do |error|
+            case error
+            when Hash
+              "Error: #{error.map { |k, v| "#{k}: #{v}" }.join(', ')}"
+            else
+              "Error: #{error}"
+            end
+          end.join("\n")
+        end
+      end
+    end # ServiceError
+
+    # Raised when Github returns the HTTP status code 400
+    class BadRequest < ServiceError
+      http_status_code 400
+    end
+
+    # Raised when GitHub returns the HTTP status code 401
+    class Unauthorized < ServiceError
+      http_status_code 401
+    end
+
+    # Raised when Github returns the HTTP status code 403
+    class Forbidden < ServiceError
+      http_status_code 403
+    end
+
+    # Raised when Github returns the HTTP status code 404
+    class NotFound < ServiceError
+      http_status_code 404
+    end
+
+    # Raised when Github returns the HTTP status code 405
+    class MethodNotAllowed < ServiceError
+      http_status_code 405
+    end
+
+    # Raised when Github returns the HTTP status code 406
+    class NotAcceptable < ServiceError
+      http_status_code 406
+    end
+
+    # Raised when GitHub returns the HTTP status code 409
+    class Conflict < ServiceError
+      http_status_code 409
+    end
+
+    # Raised when GitHub returns the HTTP status code 414
+    class UnsupportedMediaType < ServiceError
+      http_status_code 414
+    end
+
+    # Raised when GitHub returns the HTTP status code 422
+    class UnprocessableEntity < ServiceError
+      http_status_code 422
+    end
+
+    # Raised when GitHub returns the HTTP status code 451
+    class UnavailableForLegalReasons < ServiceError
+      http_status_code 451
+    end
+
+    # Raised when Github returns the HTTP status code 500
+    class InternalServerError < ServiceError
+      http_status_code 500
+    end
+
+    # Raised when Github returns the HTTP status code 501
+    class NotImplemented < ServiceError
+      http_status_code 501
+    end
+
+    # Raised when Github returns the HTTP status code 502
+    class BadGateway < ServiceError
+      http_status_code 502
+    end
+
+    # Raised when GitHub returns the HTTP status code 503
+    class ServiceUnavailable < ServiceError
+      http_status_code 503
+    end
+  end # Error
+end # Github

data/lib/github_api2/error.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+require 'descendants_tracker'
+
+module Github
+  module Error
+    class GithubError < StandardError
+      extend DescendantsTracker
+
+      attr_reader :response_message, :response_headers
+
+      # Initialize a new Github 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
+        if @response_message.respond_to?(:backtrace)
+          @response_message.backtrace
+        else
+          super
+        end
+      end
+    end # GithubError
+  end # Error
+end # Github

data/lib/github_api2/ext/faraday.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+module Faraday
+  module Utils
+
+    class ParamsHash
+      def params_encoder(encoder = nil)
+        if encoder
+          @encoder = encoder
+        elsif defined?(@encoder)
+          @encoder
+        end
+      end
+
+      def to_query(encoder = nil)
+        Utils.build_nested_query(self, nil, params_encoder)
+      end
+    end
+
+    module_function
+
+    def build_nested_query(value, prefix = nil, encoder = nil)
+      case value
+      when Array
+        value.map { |v| build_nested_query(v, "#{prefix}%5B%5D", encoder) }.join("&")
+      when Hash
+        value.map { |k, v|
+          processed_value = encoder ? encoder.escape(k) : escape(k)
+          build_nested_query(v, prefix ? "#{prefix}%5B#{processed_value}%5D" : processed_value, encoder)
+        }.join("&")
+      when NilClass
+        prefix
+      else
+        raise ArgumentError, "value must be a Hash" if prefix.nil?
+        processed_value = encoder ? encoder.escape(value) : escape(value)
+        "#{prefix}=#{processed_value}"
+      end
+    end
+  end
+end

data/lib/github_api2/mash.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Github
+  class Mash < ::Hashie::Mash
+    disable_warnings
+  end
+end