treaty 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd8fd4a097f7ff97cdb53e0d7825d79da5562d0bb6347e8e40794c158f8cb41
-  data.tar.gz: b0e119a2ba1018b4eeeb49c753b2949fb4c320ca89be29d633e7e6367cbd7360
+  metadata.gz: 6ec3d8b8448c1cb6634404040ed78864beb81a317b705a14d6f3684caaaf5952
+  data.tar.gz: a21afccd9a25da7531ff561ed4baae2cc0011ed8c9c5b09b7ceb1370b79ba353
 SHA512:
-  metadata.gz: 10514553e41066a04e066e6561744f69ca779bc4a87594bab7dce48b7e6217a5d5a6f2b7e28f1770876a9d3ff82d2f715cf4d167ef683dc36723b65a1549dc62
-  data.tar.gz: e262a6a4b2dbe068c53ced57ddcd7d9687a8e0be7d13f90ab8c2b9176015a3099829af702f59d22d28588a8c929e7178746d79356c35d4d0e899cc46991ce439
+  metadata.gz: 0a8281e2551007b9c6b514b3d8d664d484b27e757733dd6a94d191bfdf8cce1d50a5b4f3bdee8fb8e4cadb51b1b90802697f0cd06a929c8cf39482f6aef6c5c3
+  data.tar.gz: 1855561545ee10307c8094377ed28a132a6a9ac8f9347801f9f1d80e7f6adbb6fddc812b34e2b7960336d8558d84e9d48691aeea525c6357962b66e2a0a56e7e

data/README.md

@@ -13,18 +13,18 @@
 </div>
 
 > [!WARNING]
-> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.5.0"`) until the 1.0 release.
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.9.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 
 Explore comprehensive guides and documentation at [docs](./docs):
 
-- [Getting Started](./docs/getting-started.md) - installation and configuration
-- [Core Concepts](./docs/core-concepts.md) - understand fundamental concepts
-- [API Reference](./docs/api-reference.md) - complete API documentation
-- [Examples](./docs/examples.md) - practical real-world examples
+- [Getting Started](./docs/getting-started.md) - Installation and basic setup
+- [Core Concepts](./docs/core-concepts.md) - Fundamental concepts and architecture
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+- [Examples](./docs/examples.md) - Real-world usage examples
 - [Internationalization](./docs/internationalization.md) - I18n and multilingual support
-- [Full Documentation Index](./docs/README.md) - all documentation topics
+- [Full Documentation Index](./docs/README.md) - Complete documentation index
 
 ## 💡 Why Treaty?
 

data/config/locales/en.yml

@@ -84,7 +84,7 @@ en:
     versioning:
       # Version resolver
       resolver:
-        current_version_required: "Current version is required for validation"
+        specified_version_required: "Specified version is required for validation"
         version_not_found: "Version %{version} not found in treaty definition"
         version_deprecated: "Version %{version} is deprecated and cannot be used"
 
@@ -92,6 +92,8 @@ en:
       factory:
         invalid_default_option: "Default option for version must be true, false, or a Proc, got: %{type}"
         unknown_method: "Unknown method '%{method}' in version definition. Available methods: summary, strategy, deprecated, request, response, delegate_to"
+        default_deprecated_conflict: "Version %{version} cannot be both default and deprecated. A default version must be active and usable. Either remove 'default: true' or remove the 'deprecated' declaration."
+        multiple_defaults: "Cannot have multiple versions marked as default. Only one version can be the default. Please review your treaty definition and ensure only one version has 'default: true'."
 
       # Strategy validation
       strategy:

data/lib/treaty/exceptions/base.rb

@@ -35,6 +35,8 @@ module Treaty
     # - Validation - Attribute validation errors
     # - Execution - Service execution errors
     # - Deprecated - API version deprecation
+    # - SpecifiedVersionNotFound - No version specified and no default configured
+    # - VersionNotFound - Requested version doesn't exist
     # - Strategy - Invalid strategy specification
     # - ClassName - Treaty class not found
     # - MethodName - Unknown method in DSL

data/lib/treaty/exceptions/specified_version_not_found.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    # Raised when no API version is specified and no default version is configured
+    #
+    # ## Purpose
+    #
+    # Prevents treaty execution when the client doesn't specify a version
+    # and the treaty hasn't defined a default version to fall back to.
+    # Enforces explicit version selection for API contracts.
+    #
+    # ## Usage
+    #
+    # Raised automatically during version resolution in two scenarios:
+    #
+    # ### Scenario 1: No Version Specified, No Default Configured
+    # ```ruby
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1 do
+    #     # No default: true specified
+    #     request { string :title }
+    #     response(200) { object :post }
+    #   end
+    #
+    #   version 2 do
+    #     request { string :title }
+    #     response(200) { object :post }
+    #   end
+    # end
+    #
+    # # Client request without version header
+    # PostsTreaty.call!(version: nil, params: { title: "Test" })
+    # # => Raises Treaty::Exceptions::SpecifiedVersionNotFound
+    # # => "Specified version is required for validation"
+    # ```
+    #
+    # ### Scenario 2: Empty Version String
+    # ```ruby
+    # PostsTreaty.call!(version: "", params: { title: "Test" })
+    # # => Raises Treaty::Exceptions::SpecifiedVersionNotFound
+    # ```
+    #
+    # ### Prevention: Define Default Version
+    # ```ruby
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1 do
+    #     request { string :title }
+    #     response(200) { object :post }
+    #   end
+    #
+    #   version 2, default: true do  # Marks version 2 as default
+    #     request { string :title }
+    #     response(200) { object :post }
+    #   end
+    # end
+    #
+    # # Now works without explicit version
+    # PostsTreaty.call!(version: nil, params: { title: "Test" })
+    # # => Uses version 2 by default
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers to return appropriate HTTP status:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::SpecifiedVersionNotFound, with: :render_version_required
+    #
+    # def render_version_required(exception)
+    #   render json: {
+    #     error: exception.message,
+    #     hint: "Please specify an API version in the request header"
+    #   }, status: :bad_request  # HTTP 400
+    # end
+    # ```
+    #
+    # ## HTTP Status
+    #
+    # Typically returns HTTP 400 Bad Request, indicating that the client
+    # failed to provide required version information.
+    #
+    # ## Best Practices
+    #
+    # ### For API Providers
+    #
+    # 1. **Always define a default version** for backward compatibility:
+    #    ```ruby
+    #    version 1, default: true do
+    #      # ...
+    #    end
+    #    ```
+    #
+    # 2. **Document version requirements** in API documentation
+    #
+    # 3. **Provide helpful error messages** in rescue handlers
+    #
+    # ### For API Clients
+    #
+    # 1. **Always specify version explicitly** in production code
+    # 2. **Don't rely on default versions** for critical applications
+    # 3. **Handle this exception** with version selection logic
+    #
+    # ## Difference from VersionNotFound
+    #
+    # - **SpecifiedVersionNotFound**: No version specified (nil/blank)
+    # - **VersionNotFound**: Specific version specified but doesn't exist
+    #
+    # ## Version Selection Flow
+    #
+    # 1. Client provides version → Use specified version
+    # 2. Client provides no version → Look for default version
+    # 3. No default version configured → Raise SpecifiedVersionNotFound
+    class SpecifiedVersionNotFound < Base
+    end
+  end
+end

data/lib/treaty/exceptions/version_default_deprecated_conflict.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    # Raised when a version is marked as both default and deprecated
+    #
+    # ## Purpose
+    #
+    # Prevents the logical contradiction of having a version that is both
+    # the default version (used when no version is specified) and deprecated
+    # (should not be used). A default version must be active and usable.
+    #
+    # ## Usage
+    #
+    # This exception is raised automatically during version definition validation:
+    #
+    # ### Invalid Configuration
+    # ```ruby
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1, default: true do
+    #     deprecated true  # ERROR: Cannot be both default and deprecated
+    #     # ... rest of version definition
+    #   end
+    # end
+    # ```
+    #
+    # ### Valid Configurations
+    # ```ruby
+    # # Option 1: Default version without deprecation
+    # version 1, default: true do
+    #   # No deprecated call - valid
+    # end
+    #
+    # # Option 2: Deprecated version without default
+    # version 1 do
+    #   deprecated true  # Valid, but not default
+    # end
+    #
+    # # Option 3: Neither default nor deprecated
+    # version 1 do
+    #   # Regular version - valid
+    # end
+    # ```
+    #
+    # ## When It's Raised
+    #
+    # The exception is raised during treaty class loading when:
+    # 1. A version has `default: true` in the version declaration
+    # 2. AND the same version calls `deprecated` method with any truthy value or block
+    #
+    # ## Integration
+    #
+    # This is a configuration error that should be caught during development.
+    # It can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::VersionDefaultDeprecatedConflict, with: :render_config_error
+    #
+    # def render_config_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error  # HTTP 500
+    # end
+    # ```
+    #
+    # ## HTTP Status
+    #
+    # Returns HTTP 500 Internal Server Error as this indicates a configuration
+    # problem in the application code that should be fixed by developers.
+    #
+    # ## Resolution
+    #
+    # To fix this error, choose one of the following:
+    # 1. Remove `default: true` if the version should be deprecated
+    # 2. Remove the `deprecated` call if the version should be default
+    # 3. Create a new version that will be the default, and deprecate the old one
+    #
+    # ## Related Exceptions
+    #
+    # - `VersionMultipleDefaults` - When multiple versions are marked as default
+    # - `Deprecated` - When attempting to use an already deprecated version
+    class VersionDefaultDeprecatedConflict < Base
+    end
+  end
+end

data/lib/treaty/exceptions/version_multiple_defaults.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    # Raised when multiple versions are marked as default in the same treaty
+    #
+    # ## Purpose
+    #
+    # Ensures that only one version in a treaty can be marked as the default.
+    # The default version is used when clients don't specify an API version
+    # in their requests, so having multiple defaults would create ambiguity.
+    #
+    # ## Usage
+    #
+    # This exception is raised automatically during version definition validation:
+    #
+    # ### Invalid Configuration
+    # ```ruby
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1, default: true do
+    #     # First default version
+    #   end
+    #
+    #   version 2, default: true do
+    #     # ERROR: Cannot have two default versions
+    #   end
+    # end
+    # ```
+    #
+    # ### Valid Configurations
+    # ```ruby
+    # # Option 1: Single default version
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1 do
+    #     # Not default
+    #   end
+    #
+    #   version 2, default: true do
+    #     # Only one default - valid
+    #   end
+    # end
+    #
+    # # Option 2: No default version (version must be explicitly specified)
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1 do
+    #     # Not default
+    #   end
+    #
+    #   version 2 do
+    #     # Not default - valid, but version must be specified in requests
+    #   end
+    # end
+    # ```
+    #
+    # ## When It's Raised
+    #
+    # The exception is raised during treaty class loading when:
+    # 1. A second version is being defined with `default: true`
+    # 2. AND another version already has `default: true`
+    #
+    # ## Integration
+    #
+    # This is a configuration error that should be caught during development.
+    # It can be rescued by application controllers:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::VersionMultipleDefaults, with: :render_config_error
+    #
+    # def render_config_error(exception)
+    #   render json: { error: exception.message }, status: :internal_server_error  # HTTP 500
+    # end
+    # ```
+    #
+    # ## HTTP Status
+    #
+    # Returns HTTP 500 Internal Server Error as this indicates a configuration
+    # problem in the application code that should be fixed by developers.
+    #
+    # ## Resolution
+    #
+    # To fix this error:
+    # 1. Identify which version should truly be the default
+    # 2. Remove `default: true` from all other versions
+    # 3. Keep only one `default: true` declaration
+    #
+    # ## Best Practice
+    #
+    # Typically, the newest stable version should be marked as default:
+    #
+    # ```ruby
+    # version 1 do
+    #   deprecated true  # Old version
+    # end
+    #
+    # version 2 do
+    #   # Stable version
+    # end
+    #
+    # version 3, default: true do
+    #   # Latest stable version - the default
+    # end
+    # ```
+    #
+    # ## Related Exceptions
+    #
+    # - `VersionDefaultDeprecatedConflict` - When a single version has both default and deprecated
+    # - `SpecifiedVersionNotFound` - When no default exists and no version is specified
+    class VersionMultipleDefaults < Base
+    end
+  end
+end

data/lib/treaty/exceptions/version_not_found.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Exceptions
+    # Raised when a specific API version is requested but doesn't exist in the treaty
+    #
+    # ## Purpose
+    #
+    # Prevents execution with non-existent API versions. Helps clients
+    # discover available versions and prevents errors from version mismatches.
+    # Ensures API versioning integrity.
+    #
+    # ## Usage
+    #
+    # Raised automatically during version resolution when a requested version
+    # is not defined in the treaty:
+    #
+    # ### Example: Requesting Non-Existent Version
+    # ```ruby
+    # class PostsTreaty < ApplicationTreaty
+    #   version 1 do
+    #     request { string :title }
+    #     response(200) { object :post }
+    #   end
+    #
+    #   version 2, default: true do
+    #     request { string :title, :summary }
+    #     response(200) { object :post }
+    #   end
+    # end
+    #
+    # # Client requests version 3 (doesn't exist)
+    # PostsTreaty.call!(version: "3", params: { title: "Test" })
+    # # => Raises Treaty::Exceptions::VersionNotFound
+    # # => "Version 3 not found in treaty definition"
+    # ```
+    #
+    # ### Example: Version Format Mismatch
+    # ```ruby
+    # # Treaty defines version 1
+    # version 1 do
+    #   # ...
+    # end
+    #
+    # # Client requests "1.0.0" (treated as different from "1")
+    # PostsTreaty.call!(version: "1.0.0", params: {})
+    # # => Raises Treaty::Exceptions::VersionNotFound if exact match not found
+    # ```
+    #
+    # ### Example: Typo in Version Number
+    # ```ruby
+    # PostsTreaty.call!(version: "v2", params: {})  # Should be "2"
+    # # => Raises Treaty::Exceptions::VersionNotFound
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be rescued by application controllers to return appropriate HTTP status:
+    #
+    # ```ruby
+    # rescue_from Treaty::Exceptions::VersionNotFound, with: :render_version_not_found
+    #
+    # def render_version_not_found(exception)
+    #   available_versions = extract_available_versions(exception)
+    #
+    #   render json: {
+    #     error: exception.message,
+    #     available_versions: available_versions,
+    #     hint: "Please use one of the available API versions"
+    #   }, status: :not_found  # HTTP 404
+    # end
+    # ```
+    #
+    # ## HTTP Status
+    #
+    # Typically returns HTTP 404 Not Found, indicating that the requested
+    # resource (API version) does not exist on the server.
+    #
+    # ## Common Scenarios
+    #
+    # ### 1. Client Using Outdated Version Number
+    # ```ruby
+    # # Version 1 was removed, only version 2 and 3 exist
+    # PostsTreaty.call!(version: "1", params: {})
+    # # => VersionNotFound
+    # ```
+    #
+    # ### 2. Client Using Future Version
+    # ```ruby
+    # # Client expects version 5 but only version 1-3 deployed
+    # PostsTreaty.call!(version: "5", params: {})
+    # # => VersionNotFound
+    # ```
+    #
+    # ### 3. Version Format Inconsistency
+    # ```ruby
+    # # Treaty uses integers, client uses semantic versioning
+    # version 1 do ... end
+    # version 2 do ... end
+    #
+    # PostsTreaty.call!(version: "v2.0.0", params: {})
+    # # => VersionNotFound (should use "2")
+    # ```
+    #
+    # ## Best Practices
+    #
+    # ### For API Providers
+    #
+    # 1. **Version numbering consistency**:
+    #    ```ruby
+    #    # Choose one format and stick with it
+    #    version 1 do ... end
+    #    version 2 do ... end
+    #    # OR
+    #    version "1.0.0" do ... end
+    #    version "2.0.0" do ... end
+    #    ```
+    #
+    # 2. **Document available versions** in API documentation
+    #
+    # 3. **Provide version discovery endpoint**:
+    #    ```ruby
+    #    GET /api/versions
+    #    # => { available_versions: ["1", "2", "3"], default: "3" }
+    #    ```
+    #
+    # 4. **Use deprecation** before removal:
+    #    ```ruby
+    #    version 1 do
+    #      deprecated true  # Warn before removing
+    #    end
+    #    ```
+    #
+    # ### For API Clients
+    #
+    # 1. **Validate version before requests**
+    # 2. **Handle version errors gracefully**
+    # 3. **Check API documentation** for available versions
+    # 4. **Implement version fallback logic** when appropriate
+    #
+    # ## Difference from SpecifiedVersionNotFound
+    #
+    # - **SpecifiedVersionNotFound**: No version specified (nil/blank), no default configured
+    # - **VersionNotFound**: Specific version specified but doesn't exist in treaty
+    #
+    # ## Difference from Deprecated
+    #
+    # - **VersionNotFound**: Version doesn't exist at all (HTTP 404)
+    # - **Deprecated**: Version exists but is marked as deprecated (HTTP 410)
+    #
+    # ## Version Resolution Order
+    #
+    # 1. Version specified → Look for exact match
+    # 2. Exact match not found → Raise VersionNotFound
+    # 3. Match found but deprecated → Raise Deprecated
+    # 4. Match found and active → Use version
+    class VersionNotFound < Base
+    end
+  end
+end

data/lib/treaty/version.rb

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

data/lib/treaty/versions/dsl.rb

@@ -15,6 +15,9 @@ module Treaty
           @version_factory = Factory.new(version:, default:)
 
           @version_factory.instance_eval(&block)
+          @version_factory.validate_after_block!
+
+          validate_multiple_defaults! if @version_factory.default_result == true
 
           collection_of_versions << @version_factory
 
@@ -24,6 +27,15 @@ module Treaty
         def collection_of_versions
           @collection_of_versions ||= Collection.new
         end
+
+        def validate_multiple_defaults!
+          existing_defaults = collection_of_versions.map(&:default_result).count(true)
+
+          return if existing_defaults.zero?
+
+          raise Treaty::Exceptions::VersionMultipleDefaults,
+                I18n.t("treaty.versioning.factory.multiple_defaults")
+        end
       end
     end
   end

data/lib/treaty/versions/factory.rb

@@ -27,6 +27,10 @@ module Treaty
         validate_default_option!
       end
 
+      def validate_after_block!
+        validate_default_deprecated_conflict!
+      end
+
       def summary(text)
         @summary_text = text
       end
@@ -88,6 +92,17 @@ module Treaty
               )
       end
 
+      def validate_default_deprecated_conflict!
+        return unless @default_result == true
+        return unless @deprecated_result == true
+
+        raise Treaty::Exceptions::VersionDefaultDeprecatedConflict,
+              I18n.t(
+                "treaty.versioning.factory.default_deprecated_conflict",
+                version: @version.version
+              )
+      end
+
       ##########################################################################
 
       def method_missing(name, *, &_block)

data/lib/treaty/versions/resolver.rb

@@ -7,15 +7,15 @@ module Treaty
         new(...).resolve!
       end
 
-      def initialize(current_version:, collection_of_versions:)
-        @current_version = current_version
+      def initialize(specified_version:, collection_of_versions:)
+        @specified_version = specified_version
         @collection_of_versions = collection_of_versions
       end
 
       def resolve!
         determined_factory =
-          if current_version_blank?
-            default_version_factory || raise_current_version_not_found!
+          if specified_version_blank?
+            default_version_factory || raise_specified_version_not_found!
           else
             version_factory || raise_version_not_found!
           end
@@ -30,7 +30,7 @@ module Treaty
       def version_factory
         @version_factory ||=
           @collection_of_versions.find do |factory|
-            factory.version.version == @current_version
+            factory.version.version == @specified_version
           end
       end
 
@@ -39,22 +39,22 @@ module Treaty
           @collection_of_versions.find(&:default_result)
       end
 
-      def current_version_blank?
-        @current_version.to_s.strip.empty?
+      def specified_version_blank?
+        @specified_version.to_s.strip.empty?
       end
 
       ##########################################################################
 
-      def raise_current_version_not_found!
-        raise Treaty::Exceptions::Validation,
-              I18n.t("treaty.versioning.resolver.current_version_required")
+      def raise_specified_version_not_found!
+        raise Treaty::Exceptions::SpecifiedVersionNotFound,
+              I18n.t("treaty.versioning.resolver.specified_version_required")
       end
 
       def raise_version_not_found!
-        raise Treaty::Exceptions::Validation,
+        raise Treaty::Exceptions::VersionNotFound,
               I18n.t(
                 "treaty.versioning.resolver.version_not_found",
-                version: @current_version
+                version: @specified_version
               )
       end
 
@@ -62,7 +62,7 @@ module Treaty
         raise Treaty::Exceptions::Deprecated,
               I18n.t(
                 "treaty.versioning.resolver.version_deprecated",
-                version: @current_version
+                version: @specified_version
               )
       end
     end

data/lib/treaty/versions/workspace.rb

@@ -9,7 +9,7 @@ module Treaty
         super
 
         version_factory = Resolver.resolve!(
-          current_version: version,
+          specified_version: version,
           collection_of_versions: @collection_of_versions
         )
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -186,9 +186,13 @@ files:
 - lib/treaty/exceptions/method_name.rb
 - lib/treaty/exceptions/nested_attributes.rb
 - lib/treaty/exceptions/not_implemented.rb
+- lib/treaty/exceptions/specified_version_not_found.rb
 - lib/treaty/exceptions/strategy.rb
 - lib/treaty/exceptions/unexpected.rb
 - lib/treaty/exceptions/validation.rb
+- lib/treaty/exceptions/version_default_deprecated_conflict.rb
+- lib/treaty/exceptions/version_multiple_defaults.rb
+- lib/treaty/exceptions/version_not_found.rb
 - lib/treaty/info/entity/builder.rb
 - lib/treaty/info/entity/dsl.rb
 - lib/treaty/info/entity/result.rb