hati-jsonapi-error 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5c0d7b15ad75fc5e3cc6671e4468ad84d34414d7806f5fb08f7f27d03cdad0f
+  data.tar.gz: 2dfc99d96da5c7f1f65023d7120755deac9ecb42a62f5bc5b49fe36c584c77ff
+SHA512:
+  metadata.gz: 2d320265c9f28b71b6421fe04e6341e7d877c53ac99ff7c2667e3fb2f96d4d24cc094db3509b3ee2fcc851aa053632ed422730da3e89c620cf011751d6946f60
+  data.tar.gz: d5e54f2fd110a5ab0e0e13abd51b1d54bc9cf8f0b7060332cff16c1ceeff447cac7616621b4b2b89262ae1bdc8047bcddfdf492d23b94ff27a06a5e41faabc56

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hackico.ai
+
+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,391 @@
+# Hati JSON:API Error
+
+[![Gem Version](https://badge.fury.io/rb/hati-jsonapi-error.svg)](https://badge.fury.io/rb/hati-jsonapi-error)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-ruby.svg)](https://ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/hackico-ai/ruby-hati-jsonapi-error)
+
+> **Production-ready JSON:API-compliant error responses for professional Web APIs**
+
+Transform inconsistent error handling into standardized, traceable responses. Built for Ruby applications requiring enterprise-grade error management.
+
+## Why Standardized Error Handling Matters
+
+### The Problem: Inconsistent Error Responses
+
+Different controllers returning different error formats creates maintenance nightmares:
+
+```ruby
+# Three different error formats in one application
+class UsersController
+  def show
+    render json: { error: "User not found" }, status: 404
+  end
+end
+
+class OrdersController
+  def create
+    render json: { message: "Validation failed", details: errors }, status: 422
+  end
+end
+
+class PaymentsController
+  def process
+    render json: { errors: errors, error_code: "INVALID", status: "failure" }, status: 400
+  end
+end
+```
+
+This forces frontend developers to handle multiple error formats:
+
+```javascript
+// Unmaintainable error handling
+if (data.error) {
+  showError(data.error); // Users format
+} else if (data.message && data.details) {
+  showError(`${data.message}: ${data.details.join(", ")}`); // Orders format
+} else if (data.errors && data.error_code) {
+  showError(`${data.error_code}: ${data.errors.join(", ")}`); // Payments format
+}
+```
+
+### The Impact
+
+- **API Documentation**: Each endpoint needs custom error documentation
+- **Error Tracking**: Different structures break centralized logging
+- **Client SDKs**: Cannot provide consistent error handling
+- **Testing**: Each format requires separate test cases
+- **Team Coordination**: New developers must learn multiple patterns
+
+### The Solution: JSON:API Standard
+
+**One format across all endpoints:**
+
+```ruby
+raise HatiJsonapiError::UnprocessableEntity.new(
+  detail: "Email address is required",
+  source: { pointer: "/data/attributes/email" }
+)
+```
+
+**Always produces standardized output:**
+
+```json
+{
+  "errors": [
+    {
+      "status": 422,
+      "code": "unprocessable_entity",
+      "title": "Validation Failed",
+      "detail": "Email address is required",
+      "source": { "pointer": "/data/attributes/email" }
+    }
+  ]
+}
+```
+
+## ✨ Features
+
+- **JSON:API Compliant** - Follows the official [JSON:API error specification](https://jsonapi.org/format/#errors)
+- **Auto-Generated Error Classes** - Dynamic HTTP status code error classes (400-511)
+- **Rich Error Context** - Support for `id`, `code`, `title`, `detail`, `status`, `meta`, `links`, `source`
+- **Error Registry** - Map custom exceptions to standardized responses
+- **Controller Integration** - Helper methods for Rails, Sinatra, and other frameworks
+- **100% Test Coverage** - Comprehensive RSpec test suite
+- **Zero Dependencies** - Lightweight and fast
+- **Production Ready** - Thread-safe and memory efficient
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'hati-jsonapi-error'
+```
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configuration
+
+```ruby
+# config/initializers/hati_jsonapi_error.rb
+HatiJsonapiError::Config.configure do |config|
+  config.load_errors!
+
+  config.map_errors = {
+    ActiveRecord::RecordNotFound => :not_found,
+    ActiveRecord::RecordInvalid   => :unprocessable_entity,
+    ArgumentError                 => :bad_request
+  }
+
+  config.use_unexpected = HatiJsonapiError::InternalServerError
+end
+```
+
+### 2. Basic Usage
+
+```ruby
+# Simple error raising
+raise HatiJsonapiError::NotFound.new
+raise HatiJsonapiError::BadRequest.new
+raise HatiJsonapiError::Unauthorized.new
+```
+
+## Usage Examples
+
+### Basic Error Handling
+
+**Access errors multiple ways:**
+
+```ruby
+# By class name
+raise HatiJsonapiError::NotFound.new
+
+# By status code
+api_err = HatiJsonapiError::Helpers::ApiErr
+raise api_err[404]
+
+# By error code
+raise api_err[:not_found]
+```
+
+### Rich Error Context
+
+**Add debugging information:**
+
+```ruby
+HatiJsonapiError::NotFound.new(
+  id: 'user_lookup_failed',
+  detail: 'User with email john@example.com was not found',
+  source: { pointer: '/data/attributes/email' },
+  meta: {
+    searched_email: 'john@example.com',
+    suggestion: 'Verify the email address is correct'
+  }
+)
+```
+
+### Multiple Validation Errors
+
+**Collect and return multiple errors:**
+
+```ruby
+errors = []
+errors << HatiJsonapiError::UnprocessableEntity.new(
+  detail: "Email format is invalid",
+  source: { pointer: '/data/attributes/email' }
+)
+errors << HatiJsonapiError::UnprocessableEntity.new(
+  detail: "Password too short",
+  source: { pointer: '/data/attributes/password' }
+)
+
+resolver = HatiJsonapiError::Resolver.new(errors)
+render json: resolver.to_json, status: resolver.status
+```
+
+## Controller Integration
+
+```ruby
+class ApiController < ApplicationController
+  include HatiJsonapiError::Helpers
+
+  rescue_from StandardError, with: :handle_error
+
+  def show
+    # ActiveRecord::RecordNotFound automatically mapped to JSON:API NotFound
+    user = User.find(params[:id])
+    render json: user
+  end
+
+  def create
+    user = User.new(user_params)
+
+    unless user.save
+      validation_error = HatiJsonapiError::UnprocessableEntity.new(
+        detail: user.errors.full_messages.join(', '),
+        source: { pointer: '/data/attributes' },
+        meta: { validation_errors: user.errors.messages }
+      )
+
+      return render_error(validation_error)
+    end
+
+    render json: user, status: :created
+  end
+end
+```
+
+### Custom Error Classes
+
+**Domain-specific errors:**
+
+```ruby
+class PaymentRequiredError < HatiJsonapiError::PaymentRequired
+  def initialize(amount:, currency: 'USD')
+    super(
+      detail: "Payment of #{amount} #{currency} required",
+      meta: {
+        required_amount: amount,
+        currency: currency,
+        payment_methods: ['credit_card', 'paypal']
+      },
+      links: {
+        payment_page: "https://app.com/billing/upgrade?amount=#{amount}"
+      }
+    )
+  end
+end
+
+# Usage
+raise PaymentRequiredError.new(amount: 29.99)
+```
+
+## Functional Programming Integration
+
+Perfect for functional programming patterns with [hati-operation gem](https://github.com/hackico-ai/ruby-hati-operation):
+
+```ruby
+require 'hati_operation'
+
+class Api::User::CreateOperation < Hati::Operation
+  ApiErr = HatiJsonapiError::Helpers::ApiErr
+
+  def call(params)
+    user_params = step validate_params(params), err: ApiErr[422]
+    user = step create_user(user_params),       err: ApiErr[409]
+    profile = step create_profile(user),        err: ApiErr[503]
+
+    Success(profile)
+  end
+
+  private
+
+  def validate_params(params)
+    return Failure('Invalid parameters') unless params[:name]
+    Success(params)
+  end
+end
+```
+
+## Configuration
+
+### Error Mapping
+
+```ruby
+HatiJsonapiError::Config.configure do |config|
+  config.map_errors = {
+    # Rails exceptions
+    ActiveRecord::RecordNotFound  => :not_found,
+    ActiveRecord::RecordInvalid   => :unprocessable_entity,
+
+    # Custom exceptions
+    AuthenticationError           => :unauthorized,
+    RateLimitError               => :too_many_requests,
+
+    # Infrastructure exceptions
+    Redis::TimeoutError          => :service_unavailable,
+    Net::ReadTimeout             => :gateway_timeout
+  }
+
+  config.use_unexpected = HatiJsonapiError::InternalServerError
+end
+```
+
+## Available Error Classes
+
+**Quick Reference - Most Common:**
+
+| Status | Class                 | Code                    |
+| ------ | --------------------- | ----------------------- |
+| 400    | `BadRequest`          | `bad_request`           |
+| 401    | `Unauthorized`        | `unauthorized`          |
+| 403    | `Forbidden`           | `forbidden`             |
+| 404    | `NotFound`            | `not_found`             |
+| 422    | `UnprocessableEntity` | `unprocessable_entity`  |
+| 429    | `TooManyRequests`     | `too_many_requests`     |
+| 500    | `InternalServerError` | `internal_server_error` |
+| 502    | `BadGateway`          | `bad_gateway`           |
+| 503    | `ServiceUnavailable`  | `service_unavailable`   |
+
+**[Complete list of all 39 HTTP status codes →](HTTP_STATUS_CODES.md)**
+
+## Testing
+
+### RSpec Integration
+
+```ruby
+# Shared examples for JSON:API compliance
+RSpec.shared_examples 'JSON:API error response' do |expected_status, expected_code|
+  it 'returns proper JSON:API error format' do
+    json = JSON.parse(response.body)
+
+    expect(response).to have_http_status(expected_status)
+    expect(json['errors'].first['status']).to eq(expected_status)
+    expect(json['errors'].first['code']).to eq(expected_code)
+  end
+end
+
+# Usage in specs
+describe 'GET #show' do
+  context 'when user not found' do
+    subject { get :show, params: { id: 'nonexistent' } }
+    include_examples 'JSON:API error response', 404, 'not_found'
+  end
+end
+```
+
+### Unit Testing
+
+```ruby
+RSpec.describe HatiJsonapiError::NotFound do
+  it 'has correct default attributes' do
+    error = described_class.new
+
+    expect(error.status).to eq(404)
+    expect(error.code).to eq(:not_found)
+    expect(error.to_h[:title]).to eq('Not Found')
+  end
+end
+```
+
+## Benefits
+
+**For Development Teams:**
+
+- Reduced development time with single error pattern
+- Easier onboarding for new developers
+- Better testing with standardized structure
+- Improved debugging with consistent error tracking
+
+**For Frontend/Mobile Teams:**
+
+- One error parser for entire API
+- Rich error context for better user experience
+- Easier SDK development
+
+**For Operations:**
+
+- Centralized monitoring and alerting
+- Consistent error analysis
+- Simplified documentation
+
+## Contributing
+
+```bash
+git clone https://github.com/hackico-ai/ruby-hati-jsonapi-error.git
+cd ruby-hati-jsonapi-error
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+---
+
+**Professional error handling for professional APIs**

data/hati-jsonapi-error.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hati_jsonapi_error/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'hati-jsonapi-error'
+  spec.version = HatiJsonapiError::VERSION
+  spec.authors = ['Marie Giy']
+  spec.email   = %w[giy.mariya@gmail.com]
+  spec.license = 'MIT'
+
+  spec.summary     = 'Standardized JSON: API-compliant error responses made easy for your Web API.'
+  spec.description = 'hati-jsonapi-error is a Ruby gem for Standardized JSON Error.'
+  spec.homepage    = "https://github.com/hackico-ai/#{spec.name}"
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files  = Dir['CHANGELOG.md', 'LICENSE', 'README.md', 'hati-jsonapi-error.gemspec', 'lib/**/*']
+  spec.bindir = 'bin'
+  spec.executables   = []
+  spec.require_paths = ['lib']
+
+  spec.metadata['repo_homepage']     = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/hati_jsonapi_error/api_error/base_error.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This is the base error class for all errors in the HatiJsonapiError gem.
+  class BaseError < ::StandardError
+    STR = ''
+    OBJ = {}.freeze
+
+    attr_accessor :id, :code, :title, :detail, :status, :meta, :links, :source
+
+    def initialize(**attrs)
+      @id     = attrs[:id]     || STR
+      @code   = attrs[:code]   || STR
+      @title  = attrs[:title]  || STR
+      @detail = attrs[:detail] || STR
+      @status = attrs[:status] || STR
+
+      @links  = build_links(attrs[:links])
+      @source = build_source(attrs[:source])
+      @meta   = attrs[:meta] || OBJ
+
+      super(error_message)
+    end
+
+    # NOTE: used in lib/hati_jsonapi_error/payload_adapter.rb
+    def to_h
+      {
+        id: id,
+        links: links.to_h,
+        status: status,
+        code: code,
+        title: title,
+        detail: detail,
+        source: source.to_h,
+        meta: meta
+      }
+    end
+
+    def to_s
+      to_h.to_s
+    end
+
+    def serializable_hash
+      to_h
+    end
+
+    def to_json(*_args)
+      serializable_hash.to_json
+    end
+
+    private
+
+    def build_links(links_attrs)
+      links_attrs ? Links.new(**links_attrs) : OBJ
+    end
+
+    def build_source(source_attrs)
+      source_attrs ? Source.new(**source_attrs) : OBJ
+    end
+
+    def error_message
+      @detail.empty? ? @title : @detail
+    end
+  end
+end

data/lib/hati_jsonapi_error/api_error/error_const.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # rubocop:disable Layout/LineLength
+  CLIENT = {
+    400 => { name: 'BadRequest',                   code: :bad_request,                     message: 'Bad Request'                      },
+    401 => { name: 'Unauthorized',                 code: :unauthorized,                    message: 'Unauthorized'                     },
+    402 => { name: 'PaymentRequired',              code: :payment_required,                message: 'Payment Required'                 },
+    403 => { name: 'Forbidden',                    code: :forbidden,                       message: 'Forbidden'                        },
+    404 => { name: 'NotFound',                     code: :not_found,                       message: 'Not Found'                        },
+    405 => { name: 'MethodNotAllowed',             code: :method_not_allowed,              message: 'Method Not Allowed'               },
+    406 => { name: 'NotAcceptable',                code: :not_acceptable,                  message: 'Not Acceptable'                   },
+    407 => { name: 'ProxyAuthenticationRequired',  code: :proxy_authentication_required,   message: 'Proxy Authentication Required'    },
+    408 => { name: 'RequestTimeout',               code: :request_timeout,                 message: 'Request Timeout'                  },
+    409 => { name: 'Conflict',                     code: :conflict,                        message: 'Conflict'                         },
+    410 => { name: 'Gone',                         code: :gone,                            message: 'Gone'                             },
+    411 => { name: 'LengthRequired',               code: :length_required,                 message: 'Length Required'                  },
+    412 => { name: 'PreconditionFailed',           code: :precondition_failed,             message: 'Precondition Failed'              },
+    413 => { name: 'RequestEntityTooLarge',        code: :request_entity_too_large,        message: 'Request Entity Too Large'         },
+    414 => { name: 'RequestUriTooLong',            code: :request_uri_too_long,            message: 'Request Uri Too Long'             },
+    415 => { name: 'UnsupportedMediaType',         code: :unsupported_media_type,          message: 'Unsupported Media Type'           },
+    416 => { name: 'RequestedRangeNotSatisfiable', code: :requested_range_not_satisfiable, message: 'Requested Range Not Satisfiable'  },
+    417 => { name: 'ExpectationFailed',            code: :expectation_failed,              message: 'Expectation Failed'               },
+    421 => { name: 'MisdirectedRequest',           code: :misdirected_request,             message: 'Misdirected Request'              },
+    422 => { name: 'UnprocessableEntity',          code: :unprocessable_entity,            message: 'Unprocessable Entity'             },
+    423 => { name: 'Locked',                       code: :locked,                          message: 'Locked'                           },
+    424 => { name: 'FailedDependency',             code: :failed_dependency,               message: 'Failed Dependency'                },
+    425 => { name: 'TooEarly',                     code: :too_early,                       message: 'Too Early'                        },
+    426 => { name: 'UpgradeRequired',              code: :upgrade_required,                message: 'Upgrade Required'                 },
+    428 => { name: 'PreconditionRequired',         code: :precondition_required,           message: 'Precondition Required'            },
+    429 => { name: 'TooManyRequests',              code: :too_many_requests,               message: 'Too Many Requests'                },
+    431 => { name: 'RequestHeaderFieldsTooLarge',  code: :request_header_fields_too_large, message: 'Request Header Fields Too Large'  },
+    451 => { name: 'UnavailableForLegalReasons',   code: :unavailable_for_legal_reasons,   message: 'Unavailable for Legal Reasons'    }
+  }.freeze
+
+  SERVER = {
+    500 => { name: 'InternalServerError',           code: :internal_server_error,           message: 'Internal Server Error'          },
+    501 => { name: 'NotImplemented',                code: :not_implemented,                 message: 'Not Implemented'                },
+    502 => { name: 'BadGateway',                    code: :bad_gateway,                     message: 'Bad Gateway'                    },
+    503 => { name: 'ServiceUnavailable',            code: :service_unavailable,             message: 'Service Unavailable'            },
+    504 => { name: 'GatewayTimeout',                code: :gateway_timeout,                 message: 'Gateway Timeout'                },
+    505 => { name: 'HttpVersionNotSupported',       code: :http_version_not_supported,      message: 'HTTP Version Not Supported'     },
+    506 => { name: 'VariantAlsoNegotiates',         code: :variant_also_negotiates,         message: 'Variant Also Negotiates'        },
+    507 => { name: 'InsufficientStorage',           code: :insufficient_storage,            message: 'Insufficient Storage'           },
+    508 => { name: 'LoopDetected',                  code: :loop_detected,                   message: 'Loop Detected'                  },
+    509 => { name: 'BandwidthLimitExceeded',        code: :bandwidth_limit_exceeded,        message: 'Bandwidth Limit Exceeded'       },
+    510 => { name: 'NotExtended',                   code: :not_extended,                    message: 'Not Extended'                   },
+    511 => { name: 'NetworkAuthenticationRequired', code: :network_authentication_required, message: 'Network Authentication Required' }
+  }.freeze
+  # rubocop:enable Layout/LineLength
+
+  STATUS_MAP = CLIENT.merge(SERVER)
+end

data/lib/hati_jsonapi_error/api_error/links.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to build the links object for the error response.
+  class Links
+    STR = ''
+
+    attr_accessor :about, :type
+
+    def initialize(about: STR, type: STR)
+      @about = about
+      @type = type
+    end
+
+    def to_h
+      {
+        about: about,
+        type: type
+      }
+    end
+  end
+end

data/lib/hati_jsonapi_error/api_error/source.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to build the source object for the error response.
+  class Source
+    STR = ''
+
+    attr_accessor :pointer, :parameter, :header
+
+    def initialize(pointer: STR, parameter: STR, header: STR)
+      @pointer = pointer
+      @parameter = parameter
+      @header = header
+    end
+
+    def to_h
+      {
+        pointer: pointer,
+        parameter: parameter,
+        header: header
+      }
+    end
+  end
+end

data/lib/hati_jsonapi_error/config.rb

@@ -0,0 +1,42 @@
+module HatiJsonapiError
+  class Config
+    # HatiJsonapiError::Config.configure do |config|
+    #   config.load_error!
+    #   config.map_errors = {
+    #     ActiveRecord::RecordNotFound  => ApiError::NotFound,
+    #     ActiveRecord::RecordInvalid   => ApiError::UnprocessableEntity
+    #     ActiveRecord::RecordNotUnique => :conflict
+    #     ActiveRecord::Unauthorized    => 401
+    #   }
+    #   config.use_unexpected = InternalServerError
+    # end
+
+    # TODO: preload rails rescue responses
+    # - what to do about order ???order of loading is important
+    # - what to do about rails app?
+    # - what to do about rails app not loaded?
+    # - what to do about rails app not loaded?
+    class << self
+      def configure
+        yield self if block_given?
+      end
+
+      def use_unexpected=(fallback_error)
+        HatiJsonapiError::Registry.fallback = fallback_error
+      end
+
+      def map_errors=(error_map)
+        HatiJsonapiError::Registry.error_map = error_map
+      end
+
+      def error_map
+        HatiJsonapiError::Registry.error_map
+      end
+
+      # TODO: check if double defintion of errors
+      def load_errors!
+        HatiJsonapiError::Kigen.load_errors!
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/errors/helpers_handle_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # WIP: draft
+  module Errors
+    class HelpersHandleError < StandardError
+      def initialize(message = 'Invalid Helpers:handle_error')
+        super
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/errors/helpers_render_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # WIP: draft
+  module Errors
+    class HelpersRenderError < StandardError
+      def initialize(message = 'Invalid Helpers:render_error')
+        super
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/errors/not_defined_error_class_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # WIP: draft
+  module Errors
+    class NotDefinedErrorClassError < StandardError
+      def initialize(message = 'Error class not defined')
+        super
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/errors/not_loaded_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # WIP: draft
+  module Errors
+    class NotLoadedError < StandardError
+      def initialize(message = 'HatiJsonapiError::Kigen not loaded')
+        super
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/helpers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # class ApiController < ApplicationController
+  #   rescue_from ::StandardError, with: ->(e) { handle_error(e) }
+  # end
+
+  # This module contains helper methods for rendering errors in a JSON API format.
+  module Helpers
+    HatiErrs = HatiJsonapiError::Errors
+
+    def render_error(error, status: nil, short: false)
+      error_instance = error.is_a?(Class) ? error.new : error
+
+      unless error_instance.class <= HatiJsonapiError::BaseError
+        msg = "Supported only explicit type of HatiJsonapiError::BaseError, got: #{error_instance.class.name}"
+        raise HatiErrs::HelpersRenderError, msg
+      end
+
+      resolver = HatiJsonapiError::Resolver.new(error_instance)
+
+      unless defined?(render)
+        msg = 'Render not defined'
+        raise HatiErrs::HelpersRenderError, msg
+      end
+
+      render json: resolver.to_json(short: short), status: status || resolver.status
+    end
+
+    # with_original: oneOf: [false, true, :full_trace]
+    def handle_error(error, with_original: false)
+      error_class = error if error.class <= HatiJsonapiError::BaseError
+      error_class ||= HatiJsonapiError::Registry.lookup_error(error)
+
+      unless error_class
+        msg = 'Used handle_error but no mapping of default error set'
+        raise HatiErrs::HelpersHandleError, msg
+      end
+
+      # Fix: if error_class is already an instance, use it directly, otherwise create new instance
+      api_err = error_class.is_a?(Class) ? error_class.new : error_class
+      if with_original
+        api_err.meta = {
+          original_error: error.class,
+          trace: error.backtrace[0],
+          message: error.message
+        }
+        api_err.meta.merge!(backtrace: error.backtrace.join("\n")) if with_original == :full_trace
+      end
+
+      render_error(api_err)
+    end
+
+    # shorthand for API errors
+    # raise ApiErr[404] # => ApiError::NotFound
+    # raise ApiErr[:not_found] # => ApiError::NotFound
+    class ApiErr
+      class << self
+        def [](error)
+          call(error)
+        end
+
+        def call(error)
+          raise HatiErrs::NotLoadedError unless HatiJsonapiError::Kigen.loaded?
+
+          err = HatiJsonapiError::Kigen.fetch_err(error)
+
+          unless err
+            msg = "Error #{error} not defined on load_errors!. Check kigen.rb and api_error/error_const.rb"
+            raise HatiErrs::NotDefinedErrorClassError, msg
+          end
+
+          err
+        end
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/kigen.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to load all errors from STATUS_MAP in api_error/error_const.rb
+  class Kigen
+    class << self
+      # loads all errors from STATUS_MAP in api_error/error_const.rb
+      #     HatiJsonapiError::NotFound
+      #     HatiJsonapiError::BadRequest
+      #     HatiJsonapiError::Unauthorized
+      #     HatiJsonapiError::Forbidden
+      #     etc.
+      def load_errors!
+        return if loaded?
+
+        HatiJsonapiError::STATUS_MAP.each do |status, value|
+          next if HatiJsonapiError.const_defined?(value[:name])
+
+          err_klass = create_error_class(status, value)
+
+          status_klass_map[status] = err_klass
+          code_klass_map[value[:code]] = err_klass
+        end
+
+        @loaded = true
+      end
+
+      # HatiJsonapiError::Kigen.fetch_err(400) # => HatiJsonapiError::BadRequest
+      # HatiJsonapiError::Kigen.fetch_err(:bad_request)
+      def fetch_err(err)
+        return unless loaded?
+
+        status_klass_map[err] || code_klass_map[err]
+      end
+
+      # HatiJsonapiError::Kigen[400] # => HatiJsonapiError::BadRequest
+      def [](err)
+        fetch_err(err)
+      end
+
+      def loaded?
+        @loaded
+      end
+
+      def status_klass_map
+        @status_klass_map ||= {}
+      end
+
+      def code_klass_map
+        @code_klass_map ||= {}
+      end
+
+      private
+
+      def create_error_class(status, value)
+        HatiJsonapiError.const_set(value[:name], Class.new(HatiJsonapiError::BaseError) do
+          define_method :initialize do |**attrs|
+            defaults = {
+              code: value[:code],
+              message: value[:message],
+              title: value[:message],
+              status: status
+            }
+            super(**defaults.merge(attrs))
+          end
+        end)
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/poro_serializer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to serialize errors to a JSON API format.
+  class PoroSerializer
+    SHORT_KEYS = %i[status title detail source].freeze
+
+    def initialize(error)
+      @errors = normalized_errors(error)
+    end
+
+    def serialize_to_json(short: false)
+      serializable_hash(short: short).to_json
+    end
+
+    def serializable_hash(short: false)
+      if short
+        { errors: errors.map { |error| error.to_h.slice(*SHORT_KEYS) } }
+      else
+        { errors: errors.map(&:to_h) }
+      end
+    end
+
+    private
+
+    attr_reader :errors
+
+    def normalized_errors(error)
+      error.is_a?(Array) ? error : [error]
+    end
+  end
+end

data/lib/hati_jsonapi_error/registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to register errors and provide a fallback error.
+  class Registry
+    class << self
+      def fallback=(err)
+        @fallback = loaded_error?(err) ? err : fetch_error(err)
+      end
+
+      def fallback
+        @fallback ||= nil
+      end
+
+      # Base.loaded? # => true
+      # Registry.error_map = {
+      #   ActiveRecord::RecordNotFound => :not_found,
+      #   ActiveRecord::RecordInvalid  => 422
+      # }
+      def error_map=(error_map)
+        error_map.each do |error, mapped_error|
+          next if loaded_error?(mapped_error)
+
+          error_map[error] = fetch_error(mapped_error)
+        end
+
+        @error_map = error_map
+      end
+
+      def error_map
+        @error_map ||= {}
+      end
+
+      def lookup_error(error)
+        error_map[error.class] || fallback
+      end
+
+      private
+
+      def loaded_error?(error)
+        error.is_a?(Class) && error <= HatiJsonapiError::BaseError
+      end
+
+      def fetch_error(error)
+        err = HatiJsonapiError::Kigen.fetch_err(error)
+        unless err
+          msg = "Error #{error} definition not found in lib/hati_jsonapi_error/api_error/error_const.rb"
+          raise HatiJsonapiError::Errors::NotDefinedErrorClassError, msg
+        end
+
+        err
+      end
+    end
+  end
+end

data/lib/hati_jsonapi_error/resolver.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  # This class is used to resolve errors and serialize them to a JSON API format.
+  class Resolver
+    attr_reader :errors, :serializer
+
+    def initialize(api_error, serializer: PoroSerializer)
+      @errors = error_arr(api_error)
+      @serializer = serializer.new(errors)
+    end
+
+    def status
+      errors.first.status
+    end
+
+    def to_json(*_args)
+      serializer.serialize_to_json
+    end
+
+    private
+
+    def error_arr(api_error)
+      api_error.is_a?(Array) ? api_error : [api_error]
+    end
+  end
+end

data/lib/hati_jsonapi_error/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HatiJsonapiError
+  VERSION = '0.1.0'
+end

data/lib/hati_jsonapi_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'hati_jsonapi_error/version'
+
+# errors
+require 'hati_jsonapi_error/errors/helpers_handle_error'
+require 'hati_jsonapi_error/errors/helpers_render_error'
+require 'hati_jsonapi_error/errors/not_defined_error_class_error'
+require 'hati_jsonapi_error/errors/not_loaded_error'
+
+# api_error/*
+require 'hati_jsonapi_error/api_error/base_error'
+require 'hati_jsonapi_error/api_error/error_const'
+require 'hati_jsonapi_error/api_error/links'
+require 'hati_jsonapi_error/api_error/source'
+
+# logic
+require 'hati_jsonapi_error/config'
+require 'hati_jsonapi_error/kigen'
+require 'hati_jsonapi_error/helpers'
+require 'hati_jsonapi_error/poro_serializer'
+require 'hati_jsonapi_error/registry'
+require 'hati_jsonapi_error/resolver'

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: hati-jsonapi-error
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marie Giy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: hati-jsonapi-error is a Ruby gem for Standardized JSON Error.
+email:
+- giy.mariya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- hati-jsonapi-error.gemspec
+- lib/hati_jsonapi_error.rb
+- lib/hati_jsonapi_error/api_error/base_error.rb
+- lib/hati_jsonapi_error/api_error/error_const.rb
+- lib/hati_jsonapi_error/api_error/links.rb
+- lib/hati_jsonapi_error/api_error/source.rb
+- lib/hati_jsonapi_error/config.rb
+- lib/hati_jsonapi_error/errors/helpers_handle_error.rb
+- lib/hati_jsonapi_error/errors/helpers_render_error.rb
+- lib/hati_jsonapi_error/errors/not_defined_error_class_error.rb
+- lib/hati_jsonapi_error/errors/not_loaded_error.rb
+- lib/hati_jsonapi_error/helpers.rb
+- lib/hati_jsonapi_error/kigen.rb
+- lib/hati_jsonapi_error/poro_serializer.rb
+- lib/hati_jsonapi_error/registry.rb
+- lib/hati_jsonapi_error/resolver.rb
+- lib/hati_jsonapi_error/version.rb
+homepage: https://github.com/hackico-ai/hati-jsonapi-error
+licenses:
+- MIT
+metadata:
+  repo_homepage: https://github.com/hackico-ai/hati-jsonapi-error
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/hackico-ai/hati-jsonapi-error
+  changelog_uri: https://github.com/hackico-ai/hati-jsonapi-error/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/hackico-ai/hati-jsonapi-error
+  bug_tracker_uri: https://github.com/hackico-ai/hati-jsonapi-error/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Standardized JSON: API-compliant error responses made easy for your Web
+  API.'
+test_files: []