my_api_client 0.1.0

data/lib/generators/rails/templates/application_api_client.rb.erb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class ApplicationApiClient < MyApiClient::Base
+  # This is a super class for all API Client classes.
+  # Almost settings are inherited to child classes.
+
+  # Set the log output destination. The default is `Logger.new(STDOUT)`.
+  logger = Rails.logger
+
+  # Set the maximum number of seconds to wait on HTTP connection. If the
+  # connection does not open even after this number of seconds, the exception
+  # `MyApiClient::NetworkError` will raise. Setting nil will not time out.
+  # The default is 60 seconds.
+  #
+  # http_open_timeout 2.seconds
+
+  # Set the maximum number of seconds to block at one HTTP read. If it does not
+  # read even after this number of seconds, it will raise the exception
+  # MyApiClient::NetworkError. Setting nil will not time out. The default is 60
+  # seconds.
+  #
+  # http_read_timeout 3.seconds
+
+  # Catch the exception and re-execution after any seconds, like as ActiveJob.
+  # Please note that it is executed as a synchronous process unlike ActiveJob.
+  #
+  # retry_on MyApiClient::NetworkError, wait: 5.seconds, attempts: 3
+
+  # Set a HTTP response verifyment and behavior. If conflicting conditions are
+  # set, the processing defined later takes precedence
+  #
+  # error_handling status_code: 400..499, raise: MyApiClient::ClientError
+  # error_handling status_code: 500..599, raise: MyApiClient::ServerError
+end

data/lib/generators/rspec/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generate a new api client spec files.
+
+Example:
+    rails g rspec:api_client path/to/resource https://example.com get_user:get:path/to/resource`
+
+    This will create:
+        create  spec/api_clients/path/to/resource_api_client_spec.rb

data/lib/generators/rspec/api_client_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'generators/rspec'
+
+module Rspec
+  module Generators
+    # rails g rspec:api_client
+    class ApiClientGenerator < Base
+      source_root File.expand_path('templates', __dir__)
+
+      argument :endpoint,
+               type: :string,
+               default: 'https://example.com',
+               banner: '{schema and hostname}'
+      argument :requests,
+               type: :array,
+               default: %w[get_resource:get:path/to/resource post_resource:post:path/to/resource],
+               banner: '{action}:{method}:{path} {action}:{method}:{path}'
+
+      class_option :api_client_specs, type: :boolean, default: true
+
+      def generate_api_client_spec
+        return unless options[:api_client_specs]
+
+        file_path = File.join('spec/api_clients', "#{route_url.singularize}_api_client_spec.rb")
+        template 'api_client_spec.rb.erb', file_path
+      end
+    end
+  end
+end

data/lib/generators/rspec/templates/api_client_spec.rb.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= "#{class_name}ApiClient" %>, <%= type_metatag(:api_client) %> do
+  let(:api_client) { described_class.new }
+
+<% requests.each do |request| -%>
+<% action, http_method, pathname = request.sepalate(':') -%>
+  describe '#<%= action %>' do
+  end
+<% end -%>
+end

data/lib/my_api_client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'jsonpath'
+require 'active_support'
+require 'active_support/core_ext'
+require 'sawyer'
+require 'my_api_client/version'
+require 'my_api_client/config'
+require 'my_api_client/error_handling'
+require 'my_api_client/exceptions'
+require 'my_api_client/logger'
+require 'my_api_client/errors'
+require 'my_api_client/params/params'
+require 'my_api_client/params/request'
+require 'my_api_client/request'
+require 'my_api_client/base'
+
+if Sawyer::VERSION < '0.8.2'
+  module Sawyer
+    # NOTE: Old sawyer does not have attribute reader for response body.
+    #       But new version sawyer is conflict some gems (e.g. octkit).
+    class Response
+      attr_reader :body, :env
+
+      alias _original_initialize initialize
+
+      def initialize(agent, res, options = {})
+        @body = res.body
+        _original_initialize(agent, res, options)
+      end
+    end
+  end
+end

data/lib/my_api_client/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Description of Base
+  class Base
+    include MyApiClient::Config
+    include MyApiClient::ErrorHandling
+    include MyApiClient::Exceptions
+    include MyApiClient::Request
+
+    class_attribute :logger, instance_writer: false, default: ::Logger.new(STDOUT)
+    class_attribute :error_handlers, instance_writer: false, default: []
+
+    # NOTE: This class **MUST NOT** implement #initialize method. Because it
+    #       will become constraint that need call #super in the #initialize at
+    #       definition of the child classes.
+
+    HTTP_METHODS = %i[get post patch delete].freeze
+
+    HTTP_METHODS.each do |http_method|
+      class_eval <<~METHOD, __FILE__, __LINE__ + 1
+        # Description of #undefined
+        #
+        # @param pathname [String]
+        # @param headers [Hash, nil]
+        # @param query [Hash, nil]
+        # @param body [Hash, nil]
+        # @return [Sawyer::Resouce] description_of_returned_object
+        def #{http_method}(pathname, headers: nil, query: nil, body: nil)
+          _request :#{http_method}, pathname, headers, query, body, logger
+        end
+      METHOD
+    end
+    alias put patch
+  end
+end

data/lib/my_api_client/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Description of Config
+  module Config
+    extend ActiveSupport::Concern
+
+    CONFIG_METHODS = %i[endpoint http_read_timeout http_open_timeout].freeze
+
+    class_methods do
+      CONFIG_METHODS.each do |config_method|
+        class_eval <<~METHOD, __FILE__, __LINE__ + 1
+          def #{config_method}(#{config_method})
+            define_method :#{config_method}, -> { #{config_method} }
+          end
+        METHOD
+      end
+    end
+  end
+end

data/lib/my_api_client/error_handling.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Provides `error_handling` as DSL.
+  #
+  # @note
+  #   You need to define `class_attribute: error_handler, default: []` for the
+  #   included class.
+  # @example
+  #   error_handling status_code: 400..499, raise: MyApiClient::ClientError
+  #   error_handling status_code: 500..599 do |params, logger|
+  #     logger.warn 'Server error occurred.'
+  #     raise MyApiClient::ServerError, params
+  #   end
+  #
+  #   error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
+  #   error_handling json: { '$.errors.code': 20 }, raise: MyApiClient::ApiLimitError
+  #   error_handling json: { '$.errors.message': /Sorry/ }, raise: MyApiClient::ServerError
+  module ErrorHandling
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Description of .error_handling
+      #
+      # @param status_code [String, Range, Integer, Regexp] default: nil
+      # @param json [Hash] default: nil
+      # @param with [Symbol] default: nil
+      # @param raise [MyApiClient::Error] default: MyApiClient::Error
+      # @param block [Proc] describe_block_here
+      def error_handling(status_code: nil, json: nil, with: nil, raise: MyApiClient::Error)
+        temp = error_handlers.dup
+        temp << lambda { |response|
+          if match?(status_code, response.status) && match_all?(json, response.body)
+            if block_given?
+              ->(params, logger) { yield params, logger }
+            elsif with
+              with
+            else
+              ->(params, _logger) { raise raise, params }
+            end
+          end
+        }
+        self.error_handlers = temp
+      end
+
+      private
+
+      def match?(operator, target)
+        return true if operator.nil?
+
+        case operator
+        when String, Integer
+          operator == target
+        when Range
+          operator.include?(target)
+        when Regexp
+          operator =~ target.to_s
+        else
+          false
+        end
+      end
+
+      def match_all?(json, response_body)
+        return true if json.nil?
+        return false if response_body.blank?
+
+        json.all? do |path, operator|
+          target = JsonPath.new(path.to_s).first(response_body)
+          match?(operator, target)
+        end
+      end
+    end
+
+    # The error handlers defined later takes precedence
+    #
+    # @param response [Sawyer::Response] describe_params_here
+    # @return [Proc, Symbol, nil] description_of_returned_object
+    def error_handling(response)
+      error_handlers.reverse_each do |error_handler|
+        result = error_handler.call(response)
+        return result unless result.nil?
+      end
+      nil
+    end
+  end
+end

data/lib/my_api_client/errors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # The ancestor class for all API request error
+  class Error < StandardError
+    attr_reader :params
+
+    # Description of #initialize
+    #
+    # @param params [MyApiClient::Params::Params] describe_params_here
+    # @param error_message [String] default: nil
+    def initialize(params, error_message = nil)
+      @params = params
+      super error_message
+    end
+
+    # Returns contents as string for to be readable for human
+    #
+    # @return [String] Contents as string
+    def inspect
+      { error: super, params: params }.inspect
+    end
+  end
+
+  NETWORK_ERRORS = [
+    Faraday::ClientError,
+    OpenSSL::SSL::SSLError,
+    Net::OpenTimeout,
+    Net::ReadTimeout,
+    SocketError,
+  ].freeze
+
+  # Raises it when occurred to some network error
+  class NetworkError < Error
+    attr_reader :original_error
+
+    # Description of #initialize
+    #
+    # @param params [MyApiClient::Params::Params] describe_params_here
+    # @param original_error [StandardError] Some network error
+    def initialize(params, original_error)
+      @original_error = original_error
+      super params, original_error.message
+    end
+
+    # Returns contents as string for to be readable for human
+    #
+    # @return [String] Contents as string
+    def inspect
+      { error: original_error, params: params }.inspect
+    end
+  end
+
+  # NOTE: The built-in error classes are following. Although they are prepared
+  #       to save the trouble of defining, but you can create any error classes
+  #       which inherit the ancestor error class.
+
+  # For 4xx client error
+  class ClientError < Error; end
+
+  # For 5xx server error
+  class ServerError < Error; end
+
+  # For API request limit error
+  class ApiLimitError < Error; end
+end

data/lib/my_api_client/exceptions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Description of Exceptions
+  module Exceptions
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    # Description of #call
+    #
+    # @param args [Array<Object>] describe_args_here
+    # @return [Object] description_of_returned_object
+    def call(*args)
+      @args = args
+      send(*args)
+    rescue StandardError => e
+      @retry_count ||= 0
+      raise unless rescue_with_handler(e)
+    end
+
+    private
+
+    attr_reader :retry_count, :method_name, :args
+
+    class_methods do
+      def retry_on(*exception, wait: 1.second, attempts: 3)
+        rescue_from(*exception) do |error|
+          if retry_count < attempts
+            retry_calling(wait)
+          elsif block_given?
+            yield self, error
+          else
+            raise error
+          end
+        end
+      end
+
+      # Description of #discard_on
+      #
+      # @note
+      #   !! It is implemented following ActiveJob, but I think this method is
+      #   not useful in this gem. !!
+      # @param exception [Type] describe_exception_here
+      def discard_on(*exception)
+        rescue_from(*exception) do |error|
+          yield self, error if block_given?
+        end
+      end
+    end
+
+    def retry_calling(wait)
+      sleep(wait)
+      @retry_count += 1
+      call(*args)
+    end
+  end
+end

data/lib/my_api_client/logger.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  # Description of Logger
+  class Logger
+    attr_reader :logger, :method, :pathname
+
+    LOG_LEVEL = %i[debug info warn error fatal].freeze
+
+    # Description of #initialize
+    #
+    # @param logger [::Logger] describe_logger_here
+    # @param faraday [Faraday::Connection] describe_faraday_here
+    # @param method [String] HTTP method
+    # @param pathname [String] The path name
+    def initialize(logger, faraday, method, pathname)
+      @logger = logger
+      @method = method.to_s.upcase
+      @pathname = faraday.build_exclusive_url(pathname)
+    end
+
+    LOG_LEVEL.each do |level|
+      class_eval <<~METHOD, __FILE__, __LINE__ + 1
+        def #{level}(message)
+          logger.#{level}(format(message))
+        end
+      METHOD
+    end
+
+    private
+
+    def format(message)
+      "API request `#{method} #{pathname}`: \"#{message}\""
+    end
+  end
+end

data/lib/my_api_client/params/params.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MyApiClient
+  module Params
+    # Description of Params
+    class Params
+      attr_reader :request, :response
+
+      # Description of #initialize
+      #
+      # @param request [MyApiClient::Params::Request] describe_request_here
+      # @param response [Sawyer::Response, nil] describe_response_here
+      def initialize(request, response)
+        @request = request
+        @response = response
+      end
+
+      # Returns contents as string for to be readable for human
+      #
+      # @return [String] Contents as string
+      def inspect
+        { request: request, response: response }.inspect
+      end
+    end
+  end
+end