treaty 0.1.0 → 0.2.0

data/lib/treaty/exceptions/base.rb

@@ -2,6 +2,45 @@
 
 module Treaty
   module Exceptions
+    # Base exception class for all Treaty-specific exceptions
+    #
+    # ## Purpose
+    #
+    # Serves as the parent class for all custom exceptions in the Treaty gem.
+    # Allows catching all Treaty-related exceptions with a single rescue clause.
+    #
+    # ## Usage
+    #
+    # All Treaty exceptions inherit from this base class:
+    #
+    # ```ruby
+    # begin
+    #   Treaty::Base.call!(controller: self, params: params)
+    # rescue Treaty::Exceptions::Base => e
+    #   # Catches any Treaty-specific exception
+    #   handle_treaty_error(e)
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be used in application controllers for centralized error handling:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Base, with: :handle_treaty_error
+    # ```
+    #
+    # ## Subclasses
+    #
+    # - Validation - Attribute validation errors
+    # - Execution - Service execution errors
+    # - Deprecated - API version deprecation
+    # - Strategy - Invalid strategy specification
+    # - ClassName - Treaty class not found
+    # - MethodName - Unknown method in DSL
+    # - NestedAttributes - Nesting depth exceeded
+    # - NotImplemented - Abstract method not implemented
+    # - Unexpected - General unexpected errors
     class Base < StandardError
     end
   end

data/lib/treaty/exceptions/class_name.rb

@@ -2,6 +2,45 @@
 
 module Treaty
   module Exceptions
+    # Raised when a Treaty class cannot be found or resolved
+    #
+    # ## Purpose
+    #
+    # Indicates that the system attempted to load a Treaty class (typically via
+    # constantize) but the class does not exist in the expected location.
+    #
+    # ## Usage
+    #
+    # Raised automatically by the Controller DSL when treaty class resolution fails:
+    #
+    # ```ruby
+    # # In PostsController, looking for Gate::API::Posts::IndexTreaty
+    # def treaty_class
+    #   treaty_class_name.constantize
+    # rescue NameError
+    #   raise Treaty::Exceptions::ClassName,
+    #         I18n.t("treaty.controller.treaty_class_not_found", class_name: treaty_class_name)
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::ClassName, with: :render_treaty_class_not_found_error
+    #
+    # def render_treaty_class_not_found_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error
+    # end
+    # ```
+    #
+    # ## Common Causes
+    #
+    # - Treaty class file not created
+    # - Incorrect naming convention (should match controller name pattern)
+    # - Typo in class name
+    # - Missing autoload path configuration
     class ClassName < Base
       def initialize(class_name)
         super("Invalid class name: #{class_name}")

data/lib/treaty/exceptions/deprecated.rb

@@ -2,6 +2,52 @@
 
 module Treaty
   module Exceptions
+    # Raised when attempting to use a deprecated API version
+    #
+    # ## Purpose
+    #
+    # Prevents usage of API versions that have been marked as deprecated.
+    # Helps enforce API version lifecycle management and guides clients
+    # to migrate to newer versions.
+    #
+    # ## Usage
+    #
+    # Raised automatically during version resolution when a deprecated version is requested:
+    #
+    # ```ruby
+    # version 1 do
+    #   deprecated true  # Simple boolean
+    #   # or
+    #   deprecated(ENV['RELEASE_VERSION'].to_i >= 17)  # Conditional
+    #   # or
+    #   deprecated { some_condition? }  # Dynamic evaluation
+    #
+    #   # ... rest of version definition
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers to return appropriate HTTP status:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Deprecated, with: :render_version_deprecated
+    #
+    # def render_version_deprecated(exception)
+    #   render json: { error: exception.message }, status: :gone  # HTTP 410
+    # end
+    # ```
+    #
+    # ## HTTP Status
+    #
+    # Typically returns HTTP 410 Gone to indicate that the resource (API version)
+    # is no longer available and will not be available again.
+    #
+    # ## Version Lifecycle
+    #
+    # 1. Version is active (deprecated: false)
+    # 2. Version is deprecated (deprecated: true) - raises this exception
+    # 3. Version is removed from code
     class Deprecated < Base
     end
   end

data/lib/treaty/exceptions/execution.rb

@@ -2,6 +2,64 @@
 
 module Treaty
   module Exceptions
+    # Raised when service or executor execution fails
+    #
+    # ## Purpose
+    #
+    # Indicates errors during the execution phase, including executor resolution,
+    # service invocation, and result processing. Wraps underlying errors to provide
+    # consistent error handling across different executor types.
+    #
+    # ## Usage
+    #
+    # Raised in various execution scenarios:
+    #
+    # ### Executor Resolution
+    # ```ruby
+    # # When executor class not found
+    # raise Treaty::Exceptions::Execution,
+    #       I18n.t("treaty.execution.executor_not_found", class_name: "Posts::IndexService")
+    #
+    # # When executor not defined
+    # raise Treaty::Exceptions::Execution,
+    #       I18n.t("treaty.execution.executor_missing", version: "1.0.0")
+    # ```
+    #
+    # ### Service Execution
+    # ```ruby
+    # # Proc executor error
+    # begin
+    #   executor.call(params: validated_params)
+    # rescue StandardError => e
+    #   raise Treaty::Exceptions::Execution, I18n.t("treaty.execution.proc_error", message: e.message)
+    # end
+    #
+    # # Servactory service error
+    # begin
+    #   executor.call!(params: validated_params)
+    # rescue ApplicationService::Exceptions::Input => e
+    #   raise Treaty::Exceptions::Execution, I18n.t("treaty.execution.servactory_input_error", message: e.message)
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Execution, with: :render_execution_error
+    #
+    # def render_execution_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error
+    # end
+    # ```
+    #
+    # ## Executor Types
+    #
+    # Handles errors from multiple executor types:
+    # - Proc - Lambda/Proc executors
+    # - Servactory - ApplicationService-based services
+    # - Regular Class - Plain Ruby classes with custom methods
     class Execution < Base
     end
   end

data/lib/treaty/exceptions/method_name.rb

@@ -2,6 +2,53 @@
 
 module Treaty
   module Exceptions
+    # Raised when an unknown method is called in the version DSL
+    #
+    # ## Purpose
+    #
+    # Prevents typos and invalid method calls in the treaty version definition DSL.
+    # Ensures only recognized DSL methods are used within version blocks.
+    #
+    # ## Usage
+    #
+    # Raised automatically by method_missing in VersionFactory:
+    #
+    # ```ruby
+    # version 1 do
+    #   strategy Treaty::Strategy::ADAPTER  # Valid
+    #   deprecated true                     # Valid
+    #   summary "Version 1"                 # Valid
+    #
+    #   invalid_method "foo"  # Raises Treaty::Exceptions::MethodName
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Typically caught during development/testing rather than production:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::MethodName, with: :render_dsl_error
+    #
+    # def render_dsl_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error
+    # end
+    # ```
+    #
+    # ## Valid DSL Methods
+    #
+    # Within a version block, these methods are valid:
+    # - strategy(code) - Set version strategy (DIRECT/ADAPTER)
+    # - deprecated(condition) - Mark version as deprecated
+    # - summary(text) - Add version description
+    # - request(&block) - Define request schema
+    # - response(status, &block) - Define response schema
+    # - delegate_to(executor, method) - Set executor
+    #
+    # ## Prevention
+    #
+    # Always refer to Treaty documentation for valid DSL methods.
+    # This exception helps catch typos early in development.
     class MethodName < Base
     end
   end

data/lib/treaty/exceptions/nested_attributes.rb

@@ -2,6 +2,63 @@
 
 module Treaty
   module Exceptions
+    # Raised when attribute nesting depth exceeds configured maximum
+    #
+    # ## Purpose
+    #
+    # Prevents excessive nesting of attributes which can lead to:
+    # - Performance degradation
+    # - Complex validation logic
+    # - Difficult to maintain code
+    # - Stack overflow risks
+    #
+    # ## Usage
+    #
+    # Raised automatically when defining deeply nested attributes:
+    #
+    # ```ruby
+    # request do
+    #   scope :user do
+    #     object :profile do
+    #       object :settings do
+    #         object :preferences do
+    #           object :notifications do
+    #             # If max nesting is 3, this raises NestedAttributes exception
+    #             string :email_enabled
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    # end
+    # ```
+    #
+    # ## Configuration
+    #
+    # Maximum nesting level is configurable in Treaty engine configuration:
+    #
+    # ```ruby
+    # Treaty::Engine.config.treaty.attribute_nesting_level = 3  # Default
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::NestedAttributes, with: :render_nesting_error
+    #
+    # def render_nesting_error(exception)
+    #   render json: { error: exception.message }, status: :unprocessable_entity
+    # end
+    # ```
+    #
+    # ## Best Practices
+    #
+    # - Keep nesting shallow (2-3 levels maximum)
+    # - Consider flattening deeply nested structures
+    # - Use separate scopes instead of deep nesting
+    # - Refactor complex structures into simpler ones
     class NestedAttributes < Base
     end
   end

data/lib/treaty/exceptions/not_implemented.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    class NotImplemented < Base
+      # Custom NotImplementedError for Treaty
+      #
+      # ## Purpose
+      #
+      # Indicates that a required method must be implemented in a subclass.
+      # Used instead of Ruby's standard NotImplementedError to integrate with
+      # Treaty's exception handling system.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # def some_method
+      #   raise Treaty::Exceptions::NotImplemented,
+      #         I18n.t("treaty.attributes.builder.not_implemented", class: self.class)
+      # end
+      # ```
+      #
+      # ## Integration
+      #
+      # Can be rescued by application controllers using rescue_from:
+      #
+      # ```ruby
+      # rescue_from Treaty::Exceptions::NotImplemented, with: :render_not_implemented_error
+      # ```
+    end
+  end
+end

data/lib/treaty/exceptions/strategy.rb

@@ -2,6 +2,61 @@
 
 module Treaty
   module Exceptions
+    # Raised when an unknown or invalid strategy is specified
+    #
+    # ## Purpose
+    #
+    # Ensures only valid strategy types are used in version definitions.
+    # Prevents typos and invalid strategy configurations.
+    #
+    # ## Usage
+    #
+    # Raised when specifying an invalid strategy in version definition:
+    #
+    # ```ruby
+    # version 1 do
+    #   strategy Treaty::Strategy::ADAPTER  # Valid
+    #   strategy Treaty::Strategy::DIRECT   # Valid
+    #
+    #   strategy :invalid_strategy  # Raises Treaty::Exceptions::Strategy
+    # end
+    # ```
+    #
+    # ## Valid Strategies
+    #
+    # Only two strategies are supported:
+    #
+    # - `Treaty::Strategy::DIRECT` - Direct pass-through mode
+    #   - No transformation between service and response
+    #   - Service output becomes response output directly
+    #   - Faster but less flexible
+    #
+    # - `Treaty::Strategy::ADAPTER` - Adapter mode (default)
+    #   - Transforms service output to match response schema
+    #   - Validates and adapts data structure
+    #   - More flexible, recommended for most cases
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Strategy, with: :render_strategy_error
+    #
+    # def render_strategy_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error
+    # end
+    # ```
+    #
+    # ## Default Behavior
+    #
+    # If no strategy is specified, ADAPTER is used by default:
+    #
+    # ```ruby
+    # version 1 do
+    #   # strategy defaults to Treaty::Strategy::ADAPTER
+    # end
+    # ```
     class Strategy < Base
     end
   end

data/lib/treaty/exceptions/unexpected.rb

@@ -2,6 +2,68 @@
 
 module Treaty
   module Exceptions
+    # Raised for unexpected errors that don't fit other exception types
+    #
+    # ## Purpose
+    #
+    # Serves as a catch-all for unexpected errors that occur during Treaty
+    # processing but don't fall into specific exception categories.
+    # Helps maintain consistent error handling across the gem.
+    #
+    # ## Usage
+    #
+    # Used for rare or unexpected edge cases:
+    #
+    # ```ruby
+    # def process_data(data)
+    #   # ... processing logic
+    # rescue => e
+    #   # Log the unexpected error for investigation
+    #   Rails.logger.error("Unexpected Treaty error: #{e.message}")
+    #
+    #   raise Treaty::Exceptions::Unexpected,
+    #         "An unexpected error occurred during processing: #{e.message}"
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers as a safety net:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Unexpected, with: :render_unexpected_error
+    #
+    # def render_unexpected_error(exception)
+    #   # Log for investigation
+    #   Rails.logger.error("Unexpected Treaty exception: #{exception.message}")
+    #   Rails.logger.error(exception.backtrace.join("\n"))
+    #
+    #   render json: { error: "An unexpected error occurred" },
+    #          status: :internal_server_error
+    # end
+    # ```
+    #
+    # ## When to Use
+    #
+    # - Edge cases not covered by specific exceptions
+    # - Defensive programming for "should never happen" scenarios
+    # - Wrapping third-party library errors
+    # - Temporary exception during development before creating specific type
+    #
+    # ## When Not to Use
+    #
+    # If the error fits an existing exception type, use that instead:
+    # - Validation errors → Treaty::Exceptions::Validation
+    # - Execution errors → Treaty::Exceptions::Execution
+    # - Configuration errors → specific exception type
+    #
+    # ## Investigation
+    #
+    # When this exception occurs in production:
+    # 1. Review logs for full context
+    # 2. Analyze stack trace
+    # 3. Consider creating a specific exception type if pattern emerges
+    # 4. Add tests to prevent recurrence
     class Unexpected < Base
     end
   end

data/lib/treaty/exceptions/validation.rb

@@ -2,6 +2,95 @@
 
 module Treaty
   module Exceptions
+    # Raised when attribute validation fails
+    #
+    # ## Purpose
+    #
+    # Indicates that data does not conform to the schema defined in the treaty.
+    # Most commonly used exception in Treaty, covering all validation scenarios
+    # including type mismatches, required fields, inclusion constraints, and more.
+    #
+    # ## Usage
+    #
+    # Raised automatically during validation in various scenarios:
+    #
+    # ### Required Field Validation
+    # ```ruby
+    # request do
+    #   string :title, :required
+    # end
+    # # Raises: "Attribute 'title' is required but was not provided or is empty"
+    # ```
+    #
+    # ### Type Validation
+    # ```ruby
+    # request do
+    #   integer :age
+    # end
+    # # Passing "25" as string raises:
+    # # "Attribute 'age' must be an Integer, got String"
+    # ```
+    #
+    # ### Inclusion Validation
+    # ```ruby
+    # request do
+    #   string :status, inclusion: ["active", "inactive"]
+    # end
+    # # Passing "pending" raises:
+    # # "Attribute 'status' must be one of: active, inactive. Got: 'pending'"
+    # ```
+    #
+    # ### Nested Structure Validation
+    # ```ruby
+    # request do
+    #   array :tags do
+    #     string :_self
+    #   end
+    # end
+    # # Passing [123, 456] raises:
+    # # "Error in array 'tags' at index 0: Element must match one of the defined types"
+    # ```
+    #
+    # ### Custom Messages
+    # ```ruby
+    # request do
+    #   string :email, required: { is: true, message: "Email is mandatory for registration" }
+    # end
+    # # Raises custom message when email is missing
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers to return appropriate HTTP status:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::Validation, with: :render_validation_error
+    #
+    # def render_validation_error(exception)
+    #   render json: { error: exception.message }, status: :unprocessable_entity  # HTTP 422
+    # end
+    # ```
+    #
+    # ## Validation Types
+    #
+    # This exception covers multiple validation scenarios:
+    #
+    # - **Required** - Attribute presence validation
+    # - **Type** - Data type validation (integer, string, array, object, datetime)
+    # - **Inclusion** - Value must be in allowed set
+    # - **Nested** - Complex structure validation (arrays, objects)
+    # - **Options** - Unknown or invalid option specifications
+    # - **Schema** - DSL definition validation
+    #
+    # ## HTTP Status
+    #
+    # Typically returns HTTP 422 Unprocessable Entity, indicating that the
+    # request was well-formed but contains semantic errors.
+    #
+    # ## Localization
+    #
+    # All validation messages support I18n for multilingual applications.
+    # Messages are defined in `config/locales/en.yml` under `treaty.attributes.validators.*`.
     class Validation < Base
     end
   end

data/lib/treaty/info/builder.rb

@@ -112,10 +112,10 @@ module Treaty
       # def validate_nesting_level!(level)
       #   return unless level > Treaty::Engine.config.treaty.attribute_nesting_level
       #
-      #   # TODO: It is necessary to implement a translation system (I18n).
       #   raise Treaty::Exceptions::NestedAttributes,
-      #         "Nesting level #{level} exceeds maximum allowed level of " \
-      #         "#{Treaty::Engine.config.treaty.attribute_nesting_level}"
+      #         I18n.t("treaty.attributes.errors.nesting_level_exceeded",
+      #                level:,
+      #                max_level: Treaty::Engine.config.treaty.attribute_nesting_level)
       # end
     end
   end

data/lib/treaty/request/attribute/attribute.rb

@@ -8,7 +8,7 @@ module Treaty
 
         def apply_defaults!
           # For request: required by default (true).
-          # TODO: It is necessary to implement a translation system (I18n).
+          # message: nil means use I18n default message from validators
           @options[:required] ||= { is: true, message: nil }
         end
 

data/lib/treaty/response/attribute/attribute.rb

@@ -8,7 +8,7 @@ module Treaty
 
         def apply_defaults!
           # For response: optional by default (false).
-          # TODO: It is necessary to implement a translation system (I18n).
+          # message: nil means use I18n default message from validators
           @options[:required] ||= { is: false, message: nil }
         end
 

data/lib/treaty/strategy.rb

@@ -16,8 +16,8 @@ module Treaty
     def validate!
       return self if LIST.include?(@code)
 
-      # TODO: It is necessary to implement a translation system (I18n).
-      raise Treaty::Exceptions::Strategy, "Unknown strategy: #{@code}"
+      raise Treaty::Exceptions::Strategy,
+            I18n.t("treaty.versioning.strategy.unknown", strategy: @code)
     end
 
     def direct?

data/lib/treaty/version.rb

@@ -3,7 +3,7 @@
 module Treaty
   module VERSION
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
     PRE = nil