ueki 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a26fe40e5550c573ba85ceaf58122fa63cf27c358d579b14b9c72fbe985eb637
+  data.tar.gz: e3391e1a4302b29ed51f0379f268bd4dfff89e05a1d406a04d4b87e8fcf8424d
+SHA512:
+  metadata.gz: de1e9a7eb8b7a79609ff6e78f6b0a557e85a4b907f43348aba985a3dbee989061dbf0d10a6e35060e2ea02cd2b15a5161915ee70885c12e1928bee671622b882
+  data.tar.gz: 1c6f4e75b67b4b7b9e5f77763bab3fcdd7411884fb9b0629018861831a0573602e13b6c074aa301e0ce835335663b16865cdb0e7e287eccb735f14ec96667052

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,51 @@
+require:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Security/IoMethods:
+  Exclude:
+    - "spec/ueki/http_client/fake_requester.rb"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  EnforcedStyleForLeadingUnderscores: required
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2024-08-04
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Tomohiko Mimura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,162 @@
+# Ueki
+
+Ueki provides "definition of simple request methods such as `get`, `post`, etc." and "definition and handling of error exception classes for timeout error and each status code" required for HTTP Client Library.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add ueki
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install ueki
+
+> [!CAUTION]
+> `Ueki` uses faraday by default.
+> However, it is possible to choose not to use faraday, so there is no dependency.
+> If you want to use faraday, please install [faraday](https://github.com/lostisland/faraday).
+
+## Usage
+
+Simply include the Module created by Ueki in your own HTTP Client Library.
+
+```ruby
+class BookStoreClient
+  include Ueki::HttpClient.new('http://example.com')
+
+  # Class Method
+  def self.delete_book(id)
+    delete("/books/#{id}")
+  end
+
+  # Instance Method
+  def books(limit:, offset: 0)
+    get('/books', params: { limit: limit, offset: offset })
+  end
+
+  private
+
+  def default_headers
+    h = super
+    h['X-Request-Id'] = Current.request_id if Current.request_id.present?
+    h
+  end
+end
+
+BookStoreClient.new.post('/books', params: { title: 'Programming Ruby' })
+#=> { id: 1, title: 'Programming Ruby' }
+
+BookStoreClient.new.books(limit: 5)
+#=> { books: [{ id: 1, title: 'Programming Ruby' }] }
+
+BookStoreClient.delete_book(1)
+#=> nil
+
+BookStoreClient.get('/books/1')
+#=> BookStoreClient::NotFoundError (status: 404, body: { message: 'Not Found' })
+```
+
+Exception classes are defined according to the following tree structure.
+```
+BookStoreClient
+└── Error
+    ├── RequestError
+    │   ├── TimeoutError
+    │   └── UnexpectedError
+    └── UnsuccessfulResponseError
+        ├── BadRequestError
+        │   ├── UnauthorizedError
+        │   ├── ForbiddenError
+        │   ├── NotFoundError
+        │   ├── RequestTimeoutError
+        │   ├── ConflictError
+        │   ├── UnprocessableEntityError
+        │   └── TooManyRequestsError
+        └── ServerError
+```
+
+## Why not faraday?
+
+faraday has enough features.
+However, all request error exceptions are subclasses of `Faraday::Error`.
+
+That behavior does not allow for proper exception handling, so we repeatedly implement a process that replaces the exception.
+```ruby
+class BookStoreClient
+  class Error < StandardError; end
+  class ClientError < Error; end
+  class ServerError < Error; end
+
+  def books(limit:, offset: 0)
+    connection = Faraday.new("https://example.com") do |builder|
+      builder.response :raise_error
+    end
+
+    connection.get("/books")
+  rescue Faraday::Error::ClientError
+    raise ClientError
+  end
+end
+```
+
+Ueki frees us from this tedious and redundant implementation!
+
+## How to customize
+
+"Request Processing" is not important for Ueki.
+Therefore, this part can be freely customized.
+
+There are two ways to customize.
+
+### Q. I enable keep alive and don't want to output logs?
+
+A. You can use [net_http_persistent](https://github.com/lostisland/faraday-net_http_persistent) adapter by overriding `_initialize_faraday_connection`. Set up your favorite faraday middleware to match.
+
+See [lib/ueki/http_client/default_requester.rb](https://github.com/tmimura39/ueki/blob/main/lib/ueki/http_client/default_requester.rb) for details.
+```ruby
+class BookStoreClient
+  include Ueki::HttpClient.new('http://example.com')
+
+  private
+
+  def _initialize_faraday_connection(request_options)
+    Faraday.new(url: self.class::ENDPOINT, headers: _default_headers, request: request_options) do |builder|
+      builder.adapter :net_http_persistent, pool_size: 5 do |http|
+        http.idle_timeout = 100
+      end
+    end
+  end
+end
+```
+
+### Q. How can I use faraday independent request processing across multiple Client Libraries?
+
+A. It is recommended to create a Requester module.
+
+A module like [lib/ueki/http_client/default_requester.rb](https://github.com/tmimura39/ueki/blob/main/lib/ueki/http_client/default_requester.rb) could be created and applied to Ueki.
+In this case, you can use "automatic exception class definition" and "exception class acquisition processing according to status code ( `#pickup_unsuccessful_response_exception_class` )"
+
+```ruby
+class BookStoreClient
+  include Ueki::HttpClient.new('http://example.com', requester: CustomRequester)
+end
+```
+
+I am happy with my current DefaultRequester.
+So this customization method is not sophisticated.
+I will gladly accept any better suggestions.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tmimura39/ueki.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/ueki/http_client/default_requester.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Ueki
+  class HttpClient
+    # HTTP Request processing is defined.
+    # You can also use your own Requester class with the same I/F.
+    module DefaultRequester
+      UNSPECIFIED = Object.new.freeze
+      private_constant :UNSPECIFIED
+
+      def get(path, params: nil, headers: {}, request_options: {}, response_body_parser: UNSPECIFIED)
+        response_body_parser = default_response_body_parser_if_unspecifiied(response_body_parser)
+        request(:get, path:, params:, headers:, request_options:, response_body_parser:)
+      end
+
+      def post(path, params: nil, headers: {}, request_options: {}, request_body_converter: UNSPECIFIED, response_body_parser: UNSPECIFIED)
+        response_body_parser = default_response_body_parser_if_unspecifiied(response_body_parser)
+        request_body_converter = default_request_body_converter_if_unspecified(request_body_converter)
+
+        headers[:"Content-Type"] ||= "application/json" unless params.nil?
+        params = request_body_converter.call(content_type: headers[:"Content-Type"], params:)
+        request(:post, path:, params:, headers:, request_options:, response_body_parser:)
+      end
+
+      def put(path, params: nil, headers: {}, request_options: {}, request_body_converter: UNSPECIFIED, response_body_parser: UNSPECIFIED)
+        response_body_parser = default_response_body_parser_if_unspecifiied(response_body_parser)
+        request_body_converter = default_request_body_converter_if_unspecified(request_body_converter)
+
+        headers[:"Content-Type"] ||= "application/json" unless params.nil?
+        params = request_body_converter.call(content_type: headers[:"Content-Type"], params:)
+        request(:put, path:, params:, headers:, request_options:, response_body_parser:)
+      end
+
+      def patch(path, params: nil, headers: {}, request_options: {}, request_body_converter: UNSPECIFIED, response_body_parser: UNSPECIFIED)
+        response_body_parser = default_response_body_parser_if_unspecifiied(response_body_parser)
+        request_body_converter = default_request_body_converter_if_unspecified(request_body_converter)
+
+        headers[:"Content-Type"] ||= "application/json" unless params.nil?
+        params = request_body_converter.call(content_type: headers[:"Content-Type"], params:)
+        request(:patch, path:, params:, headers:, request_options:, response_body_parser:)
+      end
+
+      def delete(path, params: nil, headers: {}, request_options: {}, response_body_parser: UNSPECIFIED)
+        response_body_parser = default_response_body_parser_if_unspecifiied(response_body_parser)
+        request(:delete, path:, params:, headers:, request_options:, response_body_parser:)
+      end
+
+      private
+
+      def default_response_body_parser_if_unspecifiied(response_body_parser)
+        if response_body_parser == UNSPECIFIED
+          require_relative "json_response_body_parser"
+          JsonResponseBodyParser
+        else
+          response_body_parser
+        end
+      end
+
+      def default_request_body_converter_if_unspecified(request_body_converter)
+        if request_body_converter == UNSPECIFIED
+          require_relative "request_body_converter"
+          RequestBodyConverter
+        else
+          request_body_converter
+        end
+      end
+
+      def request(method, path:, params:, headers:, request_options:, response_body_parser:)
+        response = _with_request_error_handling do
+          _request(method, path:, params:, headers:, request_options:)
+        end
+        assert_successful_response(response:, response_body_parser:)
+
+        response_body_parser.nil? ? response.body : response_body_parser.call(response.body)
+      end
+
+      def assert_successful_response(response:, response_body_parser:)
+        status = _pickup_status(response)
+        exception_class = pickup_unsuccessful_response_exception_class(status)
+        return if exception_class.nil?
+
+        message, status, body, headers = _extract_from_raw_response(response:, response_body_parser:)
+        raise exception_class.new(message, status:, body:, headers:, response:)
+      end
+
+      # ===========================================================================================
+      # The methods defined below depend on faraday.
+      # If you want to customize faraday or use another HTTP library, override the methods.
+      # If no customization is required, use the default.
+
+      def _request(method, path:, params:, headers:, request_options:)
+        _faraday_connection(request_options).public_send(method, path, params, headers)
+      end
+
+      def _faraday_connection(request_options)
+        @_faraday_connection ||= {}
+        @_faraday_connection[request_options] ||= _initialize_faraday_connection(request_options)
+      end
+
+      def _initialize_faraday_connection(request_options)
+        Faraday.new(url: self.class::ENDPOINT, headers: _default_headers, request: request_options) do |builder|
+          builder.response :logger, (defined?(Rails) ? Rails.logger : nil) do |logger|
+            logger.filter(/Authorization:\ (.*)/, "Authorization: [token]")
+          end
+
+          builder.adapter :net_http
+        end
+      end
+
+      def _default_headers
+        { user_agent: self.class.name }
+      end
+
+      def _pickup_status(response)
+        response.status
+      end
+
+      def _extract_from_raw_response(response:, response_body_parser:)
+        message = response.to_hash.except(:request_headers, :response)
+        status = response.status
+        body = response_body_parser.call(response.body)
+        headers = response.headers
+        [message, status, body, headers]
+      end
+
+      def _with_request_error_handling
+        yield
+      rescue Faraday::TimeoutError => e
+        raise self.class::TimeoutError, e
+      rescue StandardError => e
+        raise self.class::UnexpectedError, e
+      end
+    end
+  end
+end

data/lib/ueki/http_client/exception_class_builder.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ueki
+  class HttpClient
+    class ExceptionClassBuilder
+      def initialize
+        @error = Class.new(StandardError)
+        @request_error = build_request_error(@error)
+        @timeout_error = Class.new(@request_error)
+        @unexpected_error = Class.new(@request_error)
+        @unsuccessful_response_error = build_unsuccessful_response_error(@error)
+        @bad_request_error = Class.new(@unsuccessful_response_error)
+        @unauthorized_error = Class.new(@bad_request_error)
+        @forbidden_error = Class.new(@bad_request_error)
+        @not_found_error = Class.new(@bad_request_error)
+        @request_timeout_error = Class.new(@bad_request_error)
+        @conflict_error = Class.new(@bad_request_error)
+        @unprocessable_entity_error = Class.new(@bad_request_error)
+        @too_many_requests_error = Class.new(@bad_request_error)
+        @server_error = Class.new(@unsuccessful_response_error)
+      end
+
+      def exception_classes
+        {
+          Error: @error,
+          RequestError: @request_error,
+          TimeoutError: @timeout_error,
+          UnexpectedError: @unexpected_error,
+          UnsuccessfulResponseError: @unsuccessful_response_error,
+          BadRequestError: @bad_request_error,
+          UnauthorizedError: @unauthorized_error,
+          ForbiddenError: @forbidden_error,
+          NotFoundError: @not_found_error,
+          RequestTimeoutError: @request_timeout_error,
+          ConflictError: @conflict_error,
+          UnprocessableEntityError: @unprocessable_entity_error,
+          TooManyRequestsError: @too_many_requests_error,
+          ServerError: @server_error
+        }
+      end
+
+      private
+
+      def build_request_error(error)
+        Class.new(error) do
+          def initialize(exception)
+            super("#{exception.class.name}: #{exception.message}")
+          end
+        end
+      end
+
+      def build_unsuccessful_response_error(error)
+        Class.new(error) do
+          attr_reader :status, :body, :headers, :response
+
+          def initialize(message, status:, body:, headers:, response:)
+            @status = status
+            @body = body
+            @headers = headers
+            @response = response
+
+            super(message)
+          end
+        end
+      end
+    end
+    private_constant :ExceptionClassBuilder
+  end
+end

data/lib/ueki/http_client/json_response_body_parser.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ueki
+  class HttpClient
+    # Simple JSON Parser (default)
+    # If it cannot be parsed as JSON, return the value before parsing
+    module JsonResponseBodyParser
+      module_function
+
+      def call(body)
+        return if body.nil? || (body.is_a?(String) && body.empty?)
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/ueki/http_client/request_body_converter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Ueki
+  class HttpClient
+    module RequestBodyConverter
+      module_function
+
+      def call(content_type:, params:)
+        return if params.nil?
+
+        case content_type
+        when "application/json"
+          params&.to_json
+        when "application/x-www-form-urlencoded"
+          URI.encode_www_form(params)
+        else
+          params
+        end
+      end
+    end
+  end
+end

data/lib/ueki/http_client/requester_shorthand.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ueki
+  class HttpClient
+    module RequesterShorthand
+      def get(path, **args)
+        new.get(path, **args)
+      end
+
+      def post(path, **args)
+        new.post(path, **args)
+      end
+
+      def put(path, **args)
+        new.put(path, **args)
+      end
+
+      def patch(path, **args)
+        new.patch(path, **args)
+      end
+
+      def delete(path, **args)
+        new.delete(path, **args)
+      end
+    end
+    private_constant :RequesterShorthand
+  end
+end

data/lib/ueki/http_client/unsuccessful_response_exception_class_picker.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ueki
+  class HttpClient
+    module UnsuccessfulResponseExceptionClassPicker
+      def pickup_unsuccessful_response_exception_class(status)
+        case status
+        when 401
+          self.class::UnauthorizedError
+        when 403
+          self.class::ForbiddenError
+        when 404
+          self.class::NotFoundError
+        when 408
+          self.class::RequestTimeoutError
+        when 409
+          self.class::ConflictError
+        when 422
+          self.class::UnprocessableEntityError
+        when 429
+          self.class::TooManyRequestsError
+        when 400..499
+          self.class::BadRequestError
+        when 500..599
+          self.class::ServerError
+        end
+      end
+    end
+    private_constant :UnsuccessfulResponseExceptionClassPicker
+  end
+end

data/lib/ueki/http_client.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ueki
+  # Provides a module that automatically defines exception classes and methods required for the HTTP Client Library.
+  class HttpClient < Module
+    def initialize(endpoint, requester: nil)
+      super()
+      @endpoint = endpoint
+
+      @requester =
+        if requester.nil?
+          require_relative "http_client/default_requester"
+          DefaultRequester
+        else
+          requester
+        end
+
+      @exception_classes = ExceptionClassBuilder.new.exception_classes
+    end
+
+    private
+
+    def included(descendant)
+      descendant.const_set(:ENDPOINT, @endpoint)
+      @exception_classes.each_pair do |name, object|
+        descendant.const_set(name, object)
+      end
+      descendant.include @requester
+      descendant.include UnsuccessfulResponseExceptionClassPicker
+      descendant.extend RequesterShorthand
+    end
+  end
+end
+
+require_relative "http_client/exception_class_builder"
+require_relative "http_client/requester_shorthand"
+require_relative "http_client/unsuccessful_response_exception_class_picker"

data/lib/ueki/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ueki
+  VERSION = "1.0.0"
+end

data/lib/ueki.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ueki
+end
+
+require_relative "ueki/version"
+require_relative "ueki/http_client"

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ueki
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tomohiko Mimura
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-08-05 00:00:00.000000000 Z
+dependencies: []
+description: Ueki provides "simple request method" and "error exception class definition
+  and handling"
+email:
+- mito.5525@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ueki.rb
+- lib/ueki/http_client.rb
+- lib/ueki/http_client/default_requester.rb
+- lib/ueki/http_client/exception_class_builder.rb
+- lib/ueki/http_client/json_response_body_parser.rb
+- lib/ueki/http_client/request_body_converter.rb
+- lib/ueki/http_client/requester_shorthand.rb
+- lib/ueki/http_client/unsuccessful_response_exception_class_picker.rb
+- lib/ueki/version.rb
+homepage: https://github.com/tmimura39/ueki
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tmimura39/ueki
+  source_code_uri: https://github.com/tmimura39/ueki
+  changelog_uri: https://github.com/tmimura39/ueki/tree/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Module to assist in creating your Own HTTP client library
+test_files: []