treaty 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd8fd4a097f7ff97cdb53e0d7825d79da5562d0bb6347e8e40794c158f8cb41
-  data.tar.gz: b0e119a2ba1018b4eeeb49c753b2949fb4c320ca89be29d633e7e6367cbd7360
+  metadata.gz: f3115e472c191d30a9c5c8bea6bceb1ed6674437c4e82053817da35e4e94ed4f
+  data.tar.gz: e43b55d9b75c5d2ded71686319a773a814863c10e7d6c25a030151d45883ceeb
 SHA512:
-  metadata.gz: 10514553e41066a04e066e6561744f69ca779bc4a87594bab7dce48b7e6217a5d5a6f2b7e28f1770876a9d3ff82d2f715cf4d167ef683dc36723b65a1549dc62
-  data.tar.gz: e262a6a4b2dbe068c53ced57ddcd7d9687a8e0be7d13f90ab8c2b9176015a3099829af702f59d22d28588a8c929e7178746d79356c35d4d0e899cc46991ce439
+  metadata.gz: f83bdae2ce72bb4f47773ccfa3911be30fb55a5710d211778ce725d487a6b09044c838d18fa23299607ae2ade4cbe671a189ed7d0969b57f1ab7ceaf912c8680
+  data.tar.gz: 01b3769426d4b04b1fe18441c3d943aa36ad8ccca077e7f0d4bf7c5ab1179ec88ae3343c4cd09a9274a87bcf97a88707479458bf7f9fc64fac6936770f0fce06

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"
 

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_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 = 10
     PATCH = 0
     PRE = nil
 

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.10.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -186,9 +186,11 @@ 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_not_found.rb
 - lib/treaty/info/entity/builder.rb
 - lib/treaty/info/entity/dsl.rb
 - lib/treaty/info/entity/result.rb