servus 0.2.0 → 0.3.0

data/lib/servus/support/errors.rb

@@ -54,6 +54,39 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # Guard validation failure with custom code.
+      #
+      # Guards define their own error code and HTTP status via the DSL.
+      #
+      # @example
+      #   GuardError.new("Amount must be positive", code: 'invalid_amount', http_status: 422)
+      class GuardError < ServiceError
+        DEFAULT_MESSAGE = 'Guard validation failed'
+
+        # @return [String] application-specific error code
+        attr_reader :code
+
+        # @return [Symbol, Integer] HTTP status code
+        attr_reader :http_status
+
+        # Creates a new guard error with metadata.
+        #
+        # @param message [String, nil] error message
+        # @param code [String] error code for API responses (default: 'guard_failed')
+        # @param http_status [Symbol, Integer] HTTP status (default: :unprocessable_entity)
+        def initialize(message = nil, code: 'guard_failed', http_status: :unprocessable_entity)
+          super(message)
+          @code        = code
+          @http_status = http_status
+        end
+
+        def api_error = { code: code, message: message }
+      end
+
+      # --------------------------------------------------------
+      # Standard HTTP error classes
+      # --------------------------------------------------------
+
       # 400 Bad Request - malformed or invalid request data.
       class BadRequestError < ServiceError
         DEFAULT_MESSAGE = 'Bad request'
@@ -91,6 +124,126 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 405 Method Not Allowed - HTTP method not supported for this resource.
+      class MethodNotAllowedError < ServiceError
+        DEFAULT_MESSAGE = 'Method not allowed'
+
+        def http_status = :method_not_allowed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 406 Not Acceptable - requested content type cannot be provided.
+      class NotAcceptableError < ServiceError
+        DEFAULT_MESSAGE = 'Not acceptable'
+
+        def http_status = :not_acceptable
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 407 Proxy Authentication Required - proxy credentials required.
+      class ProxyAuthenticationRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Proxy authentication required'
+
+        def http_status = :proxy_authentication_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 408 Request Timeout - client did not produce a request in time.
+      class RequestTimeoutError < ServiceError
+        DEFAULT_MESSAGE = 'Request timeout'
+
+        def http_status = :request_timeout
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 409 Conflict - request conflicts with current state of the resource.
+      class ConflictError < ServiceError
+        DEFAULT_MESSAGE = 'Conflict'
+
+        def http_status = :conflict
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 410 Gone - resource is no longer available and will not be available again.
+      class GoneError < ServiceError
+        DEFAULT_MESSAGE = 'Gone'
+
+        def http_status = :gone
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 411 Length Required - Content-Length header is required.
+      class LengthRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Length required'
+
+        def http_status = :length_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 412 Precondition Failed - precondition in headers evaluated to false.
+      class PreconditionFailedError < ServiceError
+        DEFAULT_MESSAGE = 'Precondition failed'
+
+        def http_status = :precondition_failed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 413 Payload Too Large - request entity is larger than server limits.
+      class PayloadTooLargeError < ServiceError
+        DEFAULT_MESSAGE = 'Payload too large'
+
+        def http_status = :payload_too_large
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 414 URI Too Long - URI is too long for the server to process.
+      class UriTooLongError < ServiceError
+        DEFAULT_MESSAGE = 'URI too long'
+
+        def http_status = :uri_too_long
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 415 Unsupported Media Type - request entity has unsupported media type.
+      class UnsupportedMediaTypeError < ServiceError
+        DEFAULT_MESSAGE = 'Unsupported media type'
+
+        def http_status = :unsupported_media_type
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 416 Range Not Satisfiable - client requested a portion that cannot be supplied.
+      class RangeNotSatisfiableError < ServiceError
+        DEFAULT_MESSAGE = 'Range not satisfiable'
+
+        def http_status = :range_not_satisfiable
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 417 Expectation Failed - server cannot meet Expect header requirements.
+      class ExpectationFailedError < ServiceError
+        DEFAULT_MESSAGE = 'Expectation failed'
+
+        def http_status = :expectation_failed
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 418 I'm a Teapot - server refuses to brew coffee because it is a teapot.
+      class ImATeapotError < ServiceError
+        DEFAULT_MESSAGE = "I'm a teapot"
+
+        def http_status = :im_a_teapot
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 421 Misdirected Request - request was directed at a server unable to respond.
+      class MisdirectedRequestError < ServiceError
+        DEFAULT_MESSAGE = 'Misdirected request'
+
+        def http_status = :misdirected_request
+        def api_error = { code: http_status, message: message }
+      end
+
       # 422 Unprocessable Entity - semantic errors in request.
       class UnprocessableEntityError < ServiceError
         DEFAULT_MESSAGE = 'Unprocessable entity'
@@ -99,6 +252,14 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 422 Unprocessable Content - content could not be processed.
+      class UnprocessableContentError < UnprocessableEntityError
+        DEFAULT_MESSAGE = 'Unprocessable content'
+
+        def http_status = :unprocessable_content
+        def api_error = { code: http_status, message: message }
+      end
+
       # 422 Validation Error - schema or business validation failed.
       class ValidationError < UnprocessableEntityError
         DEFAULT_MESSAGE = 'Validation failed'
@@ -106,33 +267,68 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
-      # Guard validation failure with custom code.
-      #
-      # Guards define their own error code and HTTP status via the DSL.
-      #
-      # @example
-      #   GuardError.new("Amount must be positive", code: 'invalid_amount', http_status: 422)
-      class GuardError < ServiceError
-        DEFAULT_MESSAGE = 'Guard validation failed'
+      # 423 Locked - resource is locked.
+      class LockedError < ServiceError
+        DEFAULT_MESSAGE = 'Locked'
 
-        # @return [String] application-specific error code
-        attr_reader :code
+        def http_status = :locked
+        def api_error = { code: http_status, message: message }
+      end
 
-        # @return [Symbol, Integer] HTTP status code
-        attr_reader :http_status
+      # 424 Failed Dependency - request failed due to failure of a previous request.
+      class FailedDependencyError < ServiceError
+        DEFAULT_MESSAGE = 'Failed dependency'
 
-        # Creates a new guard error with metadata.
-        #
-        # @param message [String, nil] error message
-        # @param code [String] error code for API responses (default: 'guard_failed')
-        # @param http_status [Symbol, Integer] HTTP status (default: :unprocessable_entity)
-        def initialize(message = nil, code: 'guard_failed', http_status: :unprocessable_entity)
-          super(message)
-          @code        = code
-          @http_status = http_status
-        end
+        def http_status = :failed_dependency
+        def api_error = { code: http_status, message: message }
+      end
 
-        def api_error = { code: code, message: message }
+      # 425 Too Early - server unwilling to process request that might be replayed.
+      class TooEarlyError < ServiceError
+        DEFAULT_MESSAGE = 'Too early'
+
+        def http_status = :too_early
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 426 Upgrade Required - client should switch to a different protocol.
+      class UpgradeRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Upgrade required'
+
+        def http_status = :upgrade_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 428 Precondition Required - origin server requires the request to be conditional.
+      class PreconditionRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Precondition required'
+
+        def http_status = :precondition_required
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 429 Too Many Requests - user has sent too many requests in a given time.
+      class TooManyRequestsError < ServiceError
+        DEFAULT_MESSAGE = 'Too many requests'
+
+        def http_status = :too_many_requests
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 431 Request Header Fields Too Large - server unwilling to process due to header size.
+      class RequestHeaderFieldsTooLargeError < ServiceError
+        DEFAULT_MESSAGE = 'Request header fields too large'
+
+        def http_status = :request_header_fields_too_large
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 451 Unavailable For Legal Reasons - resource unavailable due to legal demands.
+      class UnavailableForLegalReasonsError < ServiceError
+        DEFAULT_MESSAGE = 'Unavailable for legal reasons'
+
+        def http_status = :unavailable_for_legal_reasons
+        def api_error = { code: http_status, message: message }
       end
 
       # 500 Internal Server Error - unexpected server-side failure.
@@ -143,6 +339,22 @@ module Servus
         def api_error = { code: http_status, message: message }
       end
 
+      # 501 Not Implemented - server does not support the functionality required.
+      class NotImplementedError < ServiceError
+        DEFAULT_MESSAGE = 'Not implemented'
+
+        def http_status = :not_implemented
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 502 Bad Gateway - server received an invalid response from upstream.
+      class BadGatewayError < ServiceError
+        DEFAULT_MESSAGE = 'Bad gateway'
+
+        def http_status = :bad_gateway
+        def api_error = { code: http_status, message: message }
+      end
+
       # 503 Service Unavailable - dependency temporarily unavailable.
       class ServiceUnavailableError < ServiceError
         DEFAULT_MESSAGE = 'Service unavailable'
@@ -150,6 +362,62 @@ module Servus
         def http_status = :service_unavailable
         def api_error = { code: http_status, message: message }
       end
+
+      # 504 Gateway Timeout - upstream server did not respond in time.
+      class GatewayTimeoutError < ServiceError
+        DEFAULT_MESSAGE = 'Gateway timeout'
+
+        def http_status = :gateway_timeout
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 505 HTTP Version Not Supported - server does not support the HTTP version.
+      class HttpVersionNotSupportedError < ServiceError
+        DEFAULT_MESSAGE = 'HTTP version not supported'
+
+        def http_status = :http_version_not_supported
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 506 Variant Also Negotiates - transparent content negotiation error.
+      class VariantAlsoNegotiatesError < ServiceError
+        DEFAULT_MESSAGE = 'Variant also negotiates'
+
+        def http_status = :variant_also_negotiates
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 507 Insufficient Storage - server unable to store the representation.
+      class InsufficientStorageError < ServiceError
+        DEFAULT_MESSAGE = 'Insufficient storage'
+
+        def http_status = :insufficient_storage
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 508 Loop Detected - server detected an infinite loop while processing.
+      class LoopDetectedError < ServiceError
+        DEFAULT_MESSAGE = 'Loop detected'
+
+        def http_status = :loop_detected
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 510 Not Extended - further extensions to the request are required.
+      class NotExtendedError < ServiceError
+        DEFAULT_MESSAGE = 'Not extended'
+
+        def http_status = :not_extended
+        def api_error = { code: http_status, message: message }
+      end
+
+      # 511 Network Authentication Required - client needs to authenticate for network access.
+      class NetworkAuthenticationRequiredError < ServiceError
+        DEFAULT_MESSAGE = 'Network authentication required'
+
+        def http_status = :network_authentication_required
+        def api_error = { code: http_status, message: message }
+      end
     end
   end
 end

data/lib/servus/support/response.rb

@@ -51,7 +51,7 @@ module Servus
       # @api private
       def initialize(success, data, error)
         @success = success
-        @data = data
+        @data = DataObject.wrap(data)
         @error = error
       end
 
@@ -69,6 +69,17 @@ module Servus
       def success?
         @success
       end
+
+      # Checks if the service execution failed.
+      #
+      # @return [Boolean] true if the service failed, false if it succeeded
+      #
+      # @example
+      #   result = MyService.call(params)
+      #   return render_error(result.error.message) if result.failure?
+      def failure?
+        !@success
+      end
     end
   end
 end

data/lib/servus/support/validator.rb

@@ -58,11 +58,11 @@ module Servus
         true
       end
 
-      # Validates service result data against the RESULT_SCHEMA.
+      # Validates service result data against the appropriate schema.
       #
-      # Checks the result.data against either an inline RESULT_SCHEMA constant or
-      # a file-based schema at app/schemas/services/namespace/result.json.
-      # Only validates successful responses; failures are skipped.
+      # For successful responses, validates against the +result+ schema.
+      # For failure responses with data, validates against the +failure+ schema.
+      # Failure responses without data are skipped.
       #
       # @param service_class [Class] the service class being validated
       # @param result [Servus::Support::Response] the response object to validate
@@ -74,16 +74,15 @@ module Servus
       #
       # @api private
       def self.validate_result!(service_class, result)
-        return result unless result.success?
-
-        schema = load_schema(service_class, 'result')
-        return result unless schema # Skip validation if no schema exists
+        schema = result_schema_for(service_class, result)
+        return result unless schema
 
         serialized_result = result.data.as_json
         validation_errors = JSON::Validator.fully_validate(schema, serialized_result)
 
         if validation_errors.any?
-          error_message = "Invalid result structure from #{service_class.name}: #{validation_errors.join(', ')}"
+          schema_type = result.success? ? 'result' : 'failure'
+          error_message = "Invalid #{schema_type} structure from #{service_class.name}: #{validation_errors.join(', ')}"
           raise Servus::Base::ValidationError, error_message
         end
 
@@ -127,7 +126,7 @@ module Servus
       # Schemas are cached after first load for performance.
       #
       # @param service_class [Class] the service class
-      # @param type [String] schema type ("arguments" or "result")
+      # @param type [String] schema type ("arguments", "result", or "failure")
       # @return [Hash, nil] the schema hash, or nil if no schema found
       #
       # @api private
@@ -141,10 +140,10 @@ module Servus
         return @schema_cache[schema_path] if @schema_cache.key?(schema_path)
 
         # Check for DSL-defined schema first
-        dsl_schema = if type == 'arguments'
-                       service_class.arguments_schema
-                     else
-                       service_class.result_schema
+        dsl_schema = case type
+                     when 'arguments' then service_class.arguments_schema
+                     when 'result'    then service_class.result_schema
+                     when 'failure'   then service_class.failure_schema
                      end
 
         inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
@@ -180,6 +179,21 @@ module Servus
         @schema_cache
       end
 
+      # Resolves the appropriate schema for a result based on its success/failure state.
+      #
+      # @param service_class [Class] the service class
+      # @param result [Servus::Support::Response] the response to resolve schema for
+      # @return [Hash, nil] the schema, or nil if none applies
+      #
+      # @api private
+      def self.result_schema_for(service_class, result)
+        if result.success?
+          load_schema(service_class, 'result')
+        elsif result.data
+          load_schema(service_class, 'failure')
+        end
+      end
+
       # Fetches schema from DSL, inline constant, or file.
       #
       # Implements the schema resolution precedence:

data/lib/servus/testing/example_builders.rb

@@ -116,6 +116,28 @@ module Servus
         Servus::Support::Response.new(true, example, nil)
       end
 
+      # Extracts example failure data values from a service's schema.
+      #
+      # Looks for `example` or `examples` keywords in the service's failure schema
+      # and returns them wrapped in a failure Response. Useful for validating failure
+      # response structure in tests.
+      #
+      # @param service_class [Class] The service class to extract examples from
+      # @param overrides [Hash] Optional values to override the schema examples
+      # @return [Servus::Support::Response] Failure response object with example data
+      #
+      # @example Basic usage
+      #   expected = servus_failure_example(ProcessPayment::Service)
+      #   # => Servus::Support::Response with failure? == true, data:
+      #   #    { reason: 'card_declined', decline_code: 'insufficient_funds' }
+      #
+      # @note Override keys can be strings or symbols; they'll be converted to symbols
+      # @note Returns empty hash if service has no failure schema defined
+      def servus_failure_example(service_class, overrides = {})
+        example = extract_example_from(service_class, :failure, overrides)
+        Servus::Support::Response.new(false, example, Servus::Support::Errors::ServiceError.new)
+      end
+
       private
 
       # Helper method to extract and merge examples from schema

data/lib/servus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Servus
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/servus.rb

@@ -20,6 +20,7 @@ require_relative 'servus/config'
 
 # Support
 require_relative 'servus/support/logger'
+require_relative 'servus/support/data_object'
 require_relative 'servus/support/response'
 require_relative 'servus/support/validator'
 require_relative 'servus/support/errors'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: servus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastian Scholl
@@ -27,14 +27,14 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 - !ruby/object:Gem::Dependency
@@ -55,14 +55,14 @@ dependencies:
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 description: Servus is a Ruby gem that provides a structured way to create and manage
@@ -97,6 +97,7 @@ files:
 - docs/features/4_logging.md
 - docs/features/5_event_bus.md
 - docs/features/6_guards.md
+- docs/features/7_lazy_resolvers.md
 - docs/features/guards_naming_convention.md
 - docs/guides/1_common_patterns.md
 - docs/guides/2_migration_guide.md
@@ -203,6 +204,10 @@ files:
 - lib/servus/extensions/async/errors.rb
 - lib/servus/extensions/async/ext.rb
 - lib/servus/extensions/async/job.rb
+- lib/servus/extensions/lazily/call.rb
+- lib/servus/extensions/lazily/errors.rb
+- lib/servus/extensions/lazily/ext.rb
+- lib/servus/extensions/lazily/resolver.rb
 - lib/servus/guard.rb
 - lib/servus/guards.rb
 - lib/servus/guards/falsey_guard.rb
@@ -211,6 +216,7 @@ files:
 - lib/servus/guards/truthy_guard.rb
 - lib/servus/helpers/controller_helpers.rb
 - lib/servus/railtie.rb
+- lib/servus/support/data_object.rb
 - lib/servus/support/errors.rb
 - lib/servus/support/logger.rb
 - lib/servus/support/message_resolver.rb
@@ -245,7 +251,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A gem for managing service objects.
 test_files: []