treaty 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3115e472c191d30a9c5c8bea6bceb1ed6674437c4e82053817da35e4e94ed4f
-  data.tar.gz: e43b55d9b75c5d2ded71686319a773a814863c10e7d6c25a030151d45883ceeb
+  metadata.gz: 6ec3d8b8448c1cb6634404040ed78864beb81a317b705a14d6f3684caaaf5952
+  data.tar.gz: a21afccd9a25da7531ff561ed4baae2cc0011ed8c9c5b09b7ceb1370b79ba353
 SHA512:
-  metadata.gz: f83bdae2ce72bb4f47773ccfa3911be30fb55a5710d211778ce725d487a6b09044c838d18fa23299607ae2ade4cbe671a189ed7d0969b57f1ab7ceaf912c8680
-  data.tar.gz: 01b3769426d4b04b1fe18441c3d943aa36ad8ccca077e7f0d4bf7c5ab1179ec88ae3343c4cd09a9274a87bcf97a88707479458bf7f9fc64fac6936770f0fce06
+  metadata.gz: 0a8281e2551007b9c6b514b3d8d664d484b27e757733dd6a94d191bfdf8cce1d50a5b4f3bdee8fb8e4cadb51b1b90802697f0cd06a929c8cf39482f6aef6c5c3
+  data.tar.gz: 1855561545ee10307c8094377ed28a132a6a9ac8f9347801f9f1d80e7f6adbb6fddc812b34e2b7960336d8558d84e9d48691aeea525c6357962b66e2a0a56e7e

data/config/locales/en.yml

@@ -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/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/version.rb

@@ -3,7 +3,7 @@
 module Treaty
   module VERSION
     MAJOR = 0
-    MINOR = 10
+    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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -190,6 +190,8 @@ files:
 - 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