servus 0.1.2 → 0.1.4

data/lib/servus/support/rescuer.rb

@@ -2,74 +2,227 @@
 
 module Servus
   module Support
-    # Module that rescues the call method from errors
+    # Provides automatic error handling for services via {ClassMethods#rescue_from}.
+    #
+    # This module enables services to declare which exceptions should be automatically
+    # caught and converted to failure responses, eliminating repetitive rescue blocks.
+    #
+    # @example Basic usage
+    #   class MyService < Servus::Base
+    #     rescue_from Net::HTTPError, Timeout::Error,
+    #       use: Servus::Support::Errors::ServiceUnavailableError
+    #
+    #     def call
+    #       make_external_api_call  # May raise Net::HTTPError
+    #     end
+    #   end
+    #
+    # @see ClassMethods#rescue_from
     module Rescuer
-      # Includes the rescuer module into the base class
+      # Sets up error rescue functionality when included.
       #
-      # @param base [Class] The base class to include the rescuer module into
+      # @param base [Class] the class including this module (typically {Servus::Base})
+      # @api private
       def self.included(base)
-        base.class_attribute :rescuable_errors, default: []
-        base.class_attribute :rescuable_error_type, default: nil
+        base.class_attribute :rescuable_configs, default: []
         base.singleton_class.prepend(CallOverride)
         base.extend(ClassMethods)
       end
 
+      # Provides success/failure methods to rescue_from blocks.
+      #
+      # This context is used when a rescue_from block is executed. It provides
+      # the same success() and failure() methods available in service call methods,
+      # allowing blocks to create appropriate Response objects.
+      #
+      # @api private
+      class BlockContext
+        def initialize
+          @result = nil
+        end
+
+        # Creates a success response.
+        #
+        # Use this in rescue_from blocks to recover from exceptions and return
+        # successful results despite the error being raised.
+        #
+        # @param data [Hash, Object] The success data to return
+        # @return [Servus::Support::Response] Success response
+        #
+        # @example
+        #   rescue_from SomeError do |exception|
+        #     success(recovered: true, original_error: exception.message)
+        #   end
+        def success(data = nil)
+          @result = Response.new(true, data, nil)
+        end
+
+        # Creates a failure response.
+        #
+        # Use this in rescue_from blocks to convert exceptions into business failures
+        # with custom messages and error types.
+        #
+        # @param message [String, nil] The error message (uses error type's DEFAULT_MESSAGE if nil)
+        # @param type [Class<Servus::Support::Errors::ServiceError>] The error type
+        # @return [Servus::Support::Response] Failure response
+        #
+        # @example
+        #   rescue_from ActiveRecord::RecordInvalid do |exception|
+        #     failure("Database error: #{exception.message}", type: InternalServerError)
+        #   end
+        def failure(message = nil, type: Servus::Support::Errors::ServiceError)
+          error = type.new(message)
+          @result = Response.new(false, nil, error)
+        end
+
+        # The response created by success() or failure().
+        #
+        # @return [Servus::Support::Response, nil] The response, or nil if neither method was called
+        # @api private
+        attr_reader :result
+      end
+
       # Class methods for rescue_from
       module ClassMethods
-        # Rescues the call method from errors
+        # Configures automatic error handling for the service.
         #
-        # By configuring error classes in the rescue_from method, the call method will rescue from those errors
-        # and return a failure response with a ServiceError and formatted error message. This prevents the need to
-        # to have excessive rescue blocks in the call method.
+        # Declares which exception classes should be automatically rescued and converted
+        # to failure responses. Without a block, exceptions are wrapped in the specified
+        # ServiceError type with a formatted message including the original exception details.
+        #
+        # When a block is provided, it receives the exception and must return either
+        # `success(data)` or `failure(message, type:)` to create the response.
+        #
+        # @example Basic usage with default error type:
+        #   class TestService < Servus::Base
+        #     rescue_from Net::HTTPError, Timeout::Error, use: ServiceUnavailableError
+        #   end
+        #
+        # @example Custom error handling with block:
+        #   class TestService < Servus::Base
+        #     rescue_from ActiveRecord::RecordInvalid do |exception|
+        #       failure("Validation failed: #{exception.message}", type: ValidationError)
+        #     end
+        #   end
         #
-        # @example:
+        # @example Recovering from errors with success:
         #   class TestService < Servus::Base
-        #     rescue_from SomeError, type: Servus::Support::Errors::ServiceError
+        #     rescue_from Stripe::CardError do |exception|
+        #       if exception.code == 'card_declined'
+        #         failure("Card declined", type: BadRequestError)
+        #       else
+        #         success(recovered: true, fallback_used: true)
+        #       end
+        #     end
         #   end
         #
-        # @param [Error] errors One or more errors to rescue from (variadic)
-        # @param [Error] use The error to be used (optional, defaults to Servus::Support::Errors::ServiceError)
-        def rescue_from(*errors, use: Servus::Support::Errors::ServiceError)
-          self.rescuable_errors = errors
-          self.rescuable_error_type = use
+        # @param errors [Class<StandardError>] One or more exception classes to rescue from
+        # @param use [Class<Servus::Support::Errors::ServiceError>] Error class to use when wrapping exceptions
+        #   (only used without block)
+        # @yield [exception] Optional block for custom error handling
+        # @yieldparam exception [StandardError] The caught exception
+        # @yieldreturn [Servus::Support::Response] Must return success() or failure() response
+        def rescue_from(*errors, use: Servus::Support::Errors::ServiceError, &block)
+          config = {
+            errors: errors,
+            error_type: use,
+            handler: block
+          }
+
+          # Add to rescuable_configs array
+          self.rescuable_configs = rescuable_configs + [config]
         end
       end
 
-      # Module that overrides the call method to rescue from errors
+      # Wraps the service's .call method with error handling logic.
+      #
+      # This module is prepended to the service's singleton class, allowing it to
+      # intercept calls and add rescue behavior before delegating to the original implementation.
+      #
+      # @api private
       module CallOverride
-        # Overrides the call method to rescue from errors
+        # Wraps the service call with automatic error rescue.
         #
-        # @param args [Hash] The arguments passed to the call method
-        # @return [Servus::Support::Response] The result of the call method
+        # If rescuable_errors are configured, wraps the call in a rescue block.
+        # Caught exceptions are converted to failure responses using {#handle_failure}.
+        #
+        # @param args [Hash] keyword arguments passed to the service
+        # @return [Servus::Support::Response] the service result or failure response
+        #
+        # @api private
         def call(**args)
-          if rescuable_errors.any?
-            begin
-              super
-            rescue *rescuable_errors => e
-              handle_failure(e, rescuable_error_type)
-            end
-          else
+          return super if rescuable_configs.empty?
+
+          begin
             super
+          rescue StandardError => e
+            handle_rescued_error(e) || raise
           end
         end
 
-        # Returns a failure response with a ServiceError and formatted error message
+        private
+
+        # Handle a rescued error by finding matching config and processing it
         #
-        # The `failure` method is an instance method of the base class, so it can't be called from this module which
-        # is rescuing the call method.
+        # @param error [StandardError] The error to handle
+        # @return [Servus::Support::Response, nil] Response if error was handled, nil otherwise
+        def handle_rescued_error(error)
+          # Find the first matching config
+          config = rescuable_configs.find do |cfg|
+            cfg[:errors].any? { |error_class| error.is_a?(error_class) }
+          end
+
+          return nil unless config
+
+          if config[:handler]
+            # Use the block handler with BlockContext
+            block_context_result(error, config)
+          else
+            # Use the default handling
+            handle_failure(error, config[:error_type])
+          end
+        end
+
+        # Instantiates a block context to handle a rescued error
+        #
+        # @param error [StandardError] the caught exception
+        # @param config [Hash] The rescue config for the current error
+        #
+        # @api private
+        def block_context_result(error, config)
+          context = BlockContext.new
+          context.instance_exec(error, &config[:handler])
+          context.result
+        end
+
+        # Creates a failure response from a rescued exception.
+        #
+        # Converts the caught exception into a ServiceError of the specified type,
+        # preserving the original exception information in the error message.
+        #
+        # @param error [StandardError] the caught exception
+        # @param type [Class] ServiceError subclass to wrap the exception in
+        # @return [Servus::Support::Response] failure response with the wrapped error
         #
-        # @param [Error] error The error to be used
-        # @param [Class] type The error type
-        # @return [Servus::Support::Response] The failure response
+        # @api private
         def handle_failure(error, type)
           error = type.new(template_error_message(error))
           Response.new(false, nil, error)
         end
 
-        # Templates the error message
+        # Formats the exception message for the ServiceError.
+        #
+        # Creates a message that includes both the exception class and its original message,
+        # providing context about what actually failed.
+        #
+        # @param error [StandardError] the caught exception
+        # @return [String] formatted error message in the format "[ExceptionClass]: message"
+        #
+        # @example
+        #   template_error_message(Net::HTTPError.new("Connection timeout"))
+        #   # => "[Net::HTTPError]: Connection timeout"
         #
-        # @param [Error] error The error to be used
-        # @return [String] The formatted error message
+        # @api private
         def template_error_message(error)
           "[#{error.class}]: #{error.message}"
         end

data/lib/servus/support/response.rb

@@ -2,7 +2,36 @@
 
 module Servus
   module Support
-    # Response class for service results
+    # Encapsulates the result of a service execution.
+    #
+    # Response objects are returned by all service calls and contain either
+    # successful data or an error, never both. Use {#success?} to determine
+    # which path to take when handling results.
+    #
+    # @example Handling a successful response
+    #   result = MyService.call(user_id: 123)
+    #   if result.success?
+    #     puts "Data: #{result.data}"
+    #     puts "Error: #{result.error}" # => nil
+    #   end
+    #
+    # @example Handling a failed response
+    #   result = MyService.call(user_id: -1)
+    #   unless result.success?
+    #     puts "Error: #{result.error.message}"
+    #     puts "Data: #{result.data}" # => nil
+    #   end
+    #
+    # @example Pattern matching in controllers
+    #   result = MyService.call(params)
+    #   if result.success?
+    #     render json: result.data, status: :ok
+    #   else
+    #     render json: result.error.message, status: :unprocessable_entity
+    #   end
+    #
+    # @see Servus::Base#success
+    # @see Servus::Base#failure
     class Response
       # [Object] The data returned by the service
       attr_reader :data
@@ -10,20 +39,33 @@ module Servus
       # [Servus::Support::Errors::ServiceError] The error returned by the service
       attr_reader :error
 
-      # Initializes a new response
+      # Creates a new response object.
       #
-      # @param success [Boolean] Whether the response was successful
-      # @param data [Object] The data returned by the service
-      # @param error [Servus::Support::Errors::ServiceError] The error returned by the service
+      # @note This is typically called by {Servus::Base#success} or {Servus::Base#failure}
+      #   rather than being instantiated directly.
+      #
+      # @param success [Boolean] true for successful responses, false for failures
+      # @param data [Object, nil] the result data (nil for failures)
+      # @param error [Servus::Support::Errors::ServiceError, nil] the error (nil for successes)
+      #
+      # @api private
       def initialize(success, data, error)
         @success = success
         @data = data
         @error = error
       end
 
-      # Returns whether the response was successful
+      # Checks if the service execution was successful.
+      #
+      # @return [Boolean] true if the service succeeded, false if it failed
       #
-      # @return [Boolean] Whether the response was successful
+      # @example
+      #   result = MyService.call(params)
+      #   if result.success?
+      #     # Handle success - result.data is available
+      #   else
+      #     # Handle failure - result.error is available
+      #   end
       def success?
         @success
       end

data/lib/servus/support/validator.rb

@@ -2,12 +2,47 @@
 
 module Servus
   module Support
-    # Validates arguments and results
+    # Handles JSON Schema validation for service arguments and results.
+    #
+    # The Validator class provides automatic validation of service inputs and outputs
+    # against JSON Schema definitions. Schemas can be defined as inline constants
+    # (ARGUMENTS_SCHEMA, RESULT_SCHEMA) or as external JSON files.
+    #
+    # @example Inline schema validation
+    #   class MyService < Servus::Base
+    #     ARGUMENTS_SCHEMA = {
+    #       type: "object",
+    #       required: ["user_id"],
+    #       properties: {
+    #         user_id: { type: "integer" }
+    #       }
+    #     }
+    #   end
+    #
+    # @example File-based schema validation
+    #   # app/schemas/services/my_service/arguments.json
+    #   # { "type": "object", "required": ["user_id"], ... }
+    #
+    # @see https://json-schema.org/specification.html
     class Validator
-      # Class-level schema cache
+      # @api private
       @schema_cache = {}
 
-      # Validate service arguments against schema
+      # Validates service arguments against the ARGUMENTS_SCHEMA.
+      #
+      # Checks arguments against either an inline ARGUMENTS_SCHEMA constant or
+      # a file-based schema at app/schemas/services/namespace/arguments.json.
+      # Validation is skipped if no schema is defined.
+      #
+      # @param service_class [Class] the service class being validated
+      # @param args [Hash] keyword arguments passed to the service
+      # @return [Boolean] true if validation passes
+      # @raise [Servus::Support::Errors::ValidationError] if arguments fail validation
+      #
+      # @example
+      #   Validator.validate_arguments!(MyService, { user_id: 123 })
+      #
+      # @api private
       def self.validate_arguments!(service_class, args)
         schema = load_schema(service_class, 'arguments')
         return true unless schema # Skip validation if no schema exists
@@ -23,7 +58,21 @@ module Servus
         true
       end
 
-      # Validate service result against schema
+      # Validates service result data against the RESULT_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.
+      #
+      # @param service_class [Class] the service class being validated
+      # @param result [Servus::Support::Response] the response object to validate
+      # @return [Servus::Support::Response] the original result if validation passes
+      # @raise [Servus::Support::Errors::ValidationError] if result data fails validation
+      #
+      # @example
+      #   Validator.validate_result!(MyService, response)
+      #
+      # @api private
       def self.validate_result!(service_class, result)
         return result unless result.success?
 
@@ -41,7 +90,21 @@ module Servus
         result
       end
 
-      # Load schema from file with caching
+      # Loads and caches a schema for a service.
+      #
+      # Implements a three-tier lookup strategy:
+      # 1. Check for schema defined via DSL method (service_class.arguments_schema/result_schema)
+      # 2. Check for inline constant (ARGUMENTS_SCHEMA or RESULT_SCHEMA)
+      # 3. Fall back to JSON file in app/schemas/services/namespace/type.json
+      #
+      # Schemas are cached after first load for performance.
+      #
+      # @param service_class [Class] the service class
+      # @param type [String] schema type ("arguments" or "result")
+      # @return [Hash, nil] the schema hash, or nil if no schema found
+      #
+      # @api private
+      # rubocop:disable Metrics/MethodLength
       def self.load_schema(service_class, type)
         # Get service path based on class name (e.g., "process_payment" from "Servus::ProcessPayment::Service")
         service_namespace = parse_service_namespace(service_class)
@@ -50,45 +113,83 @@ module Servus
         # Return from cache if available
         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
+                     end
+
         inline_schema_constant_name = "#{service_class}::#{type.upcase}_SCHEMA"
         inline_schema_constant = if Object.const_defined?(inline_schema_constant_name)
                                    Object.const_get(inline_schema_constant_name)
                                  end
 
-        @schema_cache[schema_path] = fetch_schema_from_sources(inline_schema_constant, schema_path)
+        @schema_cache[schema_path] = fetch_schema_from_sources(dsl_schema, inline_schema_constant, schema_path)
         @schema_cache[schema_path]
       end
+      # rubocop:enable Metrics/MethodLength
 
-      # Clear the schema cache (useful for testing or development)
+      # Clears the schema cache.
+      #
+      # Useful in development when schema files are modified, or in tests
+      # to ensure fresh schema loading between test cases.
+      #
+      # @return [Hash] empty hash
+      #
+      # @example In a test suite
+      #   before(:each) do
+      #     Servus::Support::Validator.clear_cache!
+      #   end
       def self.clear_cache!
         @schema_cache = {}
       end
 
-      # Returns the schema cache
+      # Returns the current schema cache.
+      #
+      # @return [Hash] cache mapping schema paths to loaded schemas
+      # @api private
       def self.cache
         @schema_cache
       end
 
-      # Fetches the schema from the sources
+      # Fetches schema from DSL, inline constant, or file.
+      #
+      # Implements the schema resolution precedence:
+      # 1. DSL-defined schema (if provided)
+      # 2. Inline constant (if provided)
+      # 3. File at schema_path (if exists)
+      # 4. nil (no schema found)
       #
-      # This method checks if the schema is defined as an inline constant or if it exists as a file. The
-      # schema is then symbolized and returned. If the schema is not found, nil is returned.
+      # @param dsl_schema [Hash, nil] schema from DSL method (e.g., schema arguments: Hash)
+      # @param inline_schema_constant [Hash, nil] inline schema constant (e.g., ARGUMENTS_SCHEMA)
+      # @param schema_path [String] file path to external schema JSON
+      # @return [Hash, nil] schema with indifferent access, or nil if not found
       #
-      # @param inline_schema_constant [Hash, String] the inline schema constant to process
-      # @param schema_path [String] the path to the schema file
-      # @return [Hash] the processed inline schema constant
-      def self.fetch_schema_from_sources(inline_schema_constant, schema_path)
-        if inline_schema_constant
+      # @api private
+      def self.fetch_schema_from_sources(dsl_schema, inline_schema_constant, schema_path)
+        if dsl_schema
+          dsl_schema.with_indifferent_access
+        elsif inline_schema_constant
           inline_schema_constant.with_indifferent_access
         elsif File.exist?(schema_path)
           JSON.load_file(schema_path).with_indifferent_access
         end
       end
 
-      # Parses the service namespace from the service class name
+      # Converts service class name to file path namespace.
+      #
+      # Transforms a class name like "Services::ProcessPayment::Service" into
+      # "services/process_payment" for locating schema files.
+      #
+      # @param service_class [Class] the service class
+      # @return [String] underscored namespace path
+      #
+      # @example
+      #   parse_service_namespace(Services::ProcessPayment::Service)
+      #   # => "services/process_payment"
       #
-      # @param service_class [Class] the service class to parse
-      # @return [String] the service namespace
+      # @api private
       def self.parse_service_namespace(service_class)
         service_class.name.split('::')[..-2].map do |s|
           s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase

data/lib/servus/testing/example_builders.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'example_extractor'
+
+module Servus
+  module Testing
+    # Provides helper methods for extracting example values from service schemas.
+    #
+    # This module is designed to be included in test files (RSpec, Minitest, etc.)
+    # to provide convenient access to schema example values. It's particularly useful
+    # for generating test fixtures without manually maintaining separate factory files.
+    #
+    # The `servus_` prefix on method names prevents naming collisions with other
+    # testing libraries and makes it clear these are Servus-specific helpers.
+    #
+    # @example Include in RSpec
+    #   # spec/spec_helper.rb
+    #   require 'servus/testing/example_builders'
+    #
+    #   RSpec.configure do |config|
+    #     config.include Servus::Testing::ExampleBuilders
+    #   end
+    #
+    # @example Include in Rails console (development)
+    #   # config/environments/development.rb
+    #   config.to_prepare do
+    #     require 'servus/testing/example_builders'
+    #
+    #     if defined?(Rails::Console)
+    #       include Servus::Testing::ExampleBuilders
+    #     end
+    #   end
+    #
+    # @example Use in tests
+    #   RSpec.describe ProcessPayment::Service do
+    #     it 'processes payment successfully' do
+    #       args = servus_arguments_example(ProcessPayment::Service, amount: 50.0)
+    #       result = ProcessPayment::Service.call(**args)
+    #
+    #       expect(result).to be_success
+    #     end
+    #   end
+    module ExampleBuilders
+      # Extracts example argument values from a service's schema.
+      #
+      # Looks for `example` or `examples` keywords in the service's arguments schema
+      # and returns them as a hash ready to be passed to the service's `.call` method.
+      #
+      # @param service_class [Class] The service class to extract examples from
+      # @param overrides [Hash] Optional values to override the schema examples
+      # @return [Hash<Symbol, Object>] Hash of example argument values with symbolized keys
+      #
+      # @example Basic usage
+      #   args = servus_arguments_example(ProcessPayment::Service)
+      #   # => { user_id: 123, amount: 100.0, currency: 'USD' }
+      #
+      #   result = ProcessPayment::Service.call(**args)
+      #
+      # @example With overrides
+      #   args = servus_arguments_example(ProcessPayment::Service, amount: 50.0, currency: 'EUR')
+      #   # => { user_id: 123, amount: 50.0, currency: 'EUR' }
+      #
+      # @example In RSpec tests
+      #   it 'processes different currencies' do
+      #     %w[USD EUR GBP].each do |currency|
+      #       result = ProcessPayment::Service.call(
+      #         **servus_arguments_example(ProcessPayment::Service, currency: currency)
+      #       )
+      #       expect(result).to be_success
+      #     end
+      #   end
+      #
+      # @note Override keys can be strings or symbols; they'll be converted to symbols
+      # @note Returns empty hash if service has no arguments schema defined
+      def servus_arguments_example(service_class, overrides = {})
+        extract_example_from(service_class, :arguments, overrides)
+      end
+
+      # Extracts example result values from a service's schema.
+      #
+      # Looks for `example` or `examples` keywords in the service's result schema
+      # and returns them as a hash. Useful for validating service response structure
+      # and expected data shapes 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] Response object with example result data
+      #
+      # @example Basic usage
+      #   expected = servus_result_example(ProcessPayment::Service)
+      #   # => Servus::Support::Response with data:
+      #   #    { transaction_id: 'txn_abc123', status: 'approved', amount_charged: 100.0 }
+      #
+      # @example Validate result structure
+      #   result = ProcessPayment::Service.call(**servus_arguments_example(ProcessPayment::Service))
+      #
+      #   expect(result.data).to match(
+      #     hash_including(servus_result_example(ProcessPayment::Service).data)
+      #   )
+      #
+      # @example Check result has expected keys
+      #   result = ProcessPayment::Service.call(**args)
+      #   expected_keys = servus_result_example(ProcessPayment::Service).data.keys
+      #
+      #   expect(result.data.keys).to match_array(expected_keys)
+      #
+      # @example With overrides
+      #   expected = servus_result_example(ProcessPayment::Service, status: 'pending').data
+      #   # => { transaction_id: 'txn_abc123', status: 'pending', amount_charged: 100.0 }
+      #
+      # @note Override keys can be strings or symbols; they'll be converted to symbols
+      # @note Returns empty hash if service has no result schema defined
+      def servus_result_example(service_class, overrides = {})
+        example = extract_example_from(service_class, :result, overrides)
+        # Wrap in a successful Response object
+        Servus::Support::Response.new(true, example, nil)
+      end
+
+      private
+
+      # Helper method to extract and merge examples from schema
+      #
+      # @param service_class [Class] The service class to extract examples from
+      # @param schema_type [Symbol] The type of schema (:arguments or :result)
+      # @param overrides [Hash] Optional values to override the schema examples
+      # @return [Hash<Symbol, Object>] Hash of example values with symbolized keys
+      def extract_example_from(service_class, schema_type, overrides = {})
+        examples = ExampleExtractor.extract(service_class, schema_type)
+        examples.deep_merge(overrides.deep_symbolize_keys)
+      end
+    end
+  end
+end