servus 0.1.5 → 0.2.0

data/lib/generators/servus/guard/templates/guard.rb.erb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Guard that validates <%= file_name.humanize.downcase %> conditions.
+#
+# Guards are reusable validation rules that halt service execution when
+# conditions aren't met. They provide declarative precondition checking
+# with rich error responses.
+#
+# @example Basic usage in a service
+#   class MyService < Servus::Base
+#     def call
+#       <%= enforce_method_name %>(arg: value)
+#       # ... business logic ...
+#       success(result)
+#     end
+#   end
+#
+# @example Conditional check (returns boolean, doesn't halt)
+#   if <%= check_method_name %>(arg: value)
+#     # condition is met
+#   end
+#
+# @see Servus::Guard
+# @see Servus::Guards
+<%- end -%>
+class <%= guard_class_name %> < Servus::Guard
+  http_status 422
+  error_code '<%= file_name %>'
+
+  message '%<class_name>s <%= file_name.humanize.downcase %> validation failed' do
+    message_data
+  end
+
+  # Tests whether the <%= file_name.humanize.downcase %> condition is met.
+  #
+  # @param kwargs [Hash] the arguments to validate
+  # @return [Boolean] true if validation passes
+  def test(**kwargs)
+    # TODO: Implement validation logic
+    # Return true if the condition is met, false otherwise
+    #
+    # Example:
+    #   def test(account:, amount:)
+    #     account.balance >= amount
+    #   end
+    true
+  end
+
+  private
+
+  # Builds the interpolation data for the error message.
+  #
+  # @return [Hash] message interpolation data
+  def message_data
+    # TODO: Return hash of values for message interpolation
+    # Access guard arguments via kwargs[:argument_name]
+    #
+    # Example:
+    #   {
+    #     class_name: kwargs[:account].class.name,
+    #     balance: kwargs[:account].balance,
+    #     required: kwargs[:amount]
+    #   }
+    {
+      class_name: 'Object'
+    }
+  end
+end

data/lib/generators/servus/guard/templates/guard_spec.rb.erb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= guard_class_name %> do
+<%- unless options[:no_docs] -%>
+  # TODO: Define a test class or use a real model
+  # let(:test_class) do
+  #   Struct.new(:attribute, keyword_init: true) do
+  #     def self.name
+  #       'TestModel'
+  #     end
+  #   end
+  # end
+
+<%- end -%>
+  describe '#test' do
+<%- unless options[:no_docs] -%>
+    # TODO: Add test cases for your guard logic
+    #
+    # Example:
+    #   context 'when condition is met' do
+    #     it 'returns true' do
+    #       object = test_class.new(attribute: valid_value)
+    #       guard = described_class.new(object: object)
+    #       expect(guard.test(object: object)).to be true
+    #     end
+    #   end
+    #
+    #   context 'when condition is not met' do
+    #     it 'returns false' do
+    #       object = test_class.new(attribute: invalid_value)
+    #       guard = described_class.new(object: object)
+    #       expect(guard.test(object: object)).to be false
+    #     end
+    #   end
+
+<%- end -%>
+    it 'returns true when validation passes' do
+      guard = described_class.new
+      expect(guard.test).to be true
+    end
+  end
+
+  describe '#error' do
+    it 'returns a GuardError with correct metadata' do
+      guard = described_class.new
+      error = guard.error
+
+      expect(error).to be_a(Servus::Support::Errors::GuardError)
+      expect(error.code).to eq('<%= file_name %>')
+      expect(error.http_status).to eq(422)
+    end
+  end
+
+  describe 'method registration' do
+    it 'defines <%= enforce_method_name %> on Servus::Guards' do
+      expect(Servus::Guards.method_defined?(:<%= enforce_method_name %>)).to be true
+    end
+
+    it 'defines <%= check_method_name %> on Servus::Guards' do
+      expect(Servus::Guards.method_defined?(:<%= check_method_name %>)).to be true
+    end
+  end
+end

data/lib/servus/base.rb

@@ -49,6 +49,7 @@ module Servus
     include Servus::Support::Errors
     include Servus::Support::Rescuer
     include Servus::Events::Emitter
+    include Servus::Guards
 
     # Support class aliases
     Logger = Servus::Support::Logger
@@ -185,7 +186,14 @@ module Servus
         before_call(args)
 
         instance = new(**args)
-        result = benchmark(**args) { instance.call }
+
+        # Wrap execution in catch block to handle guard failures
+        result = catch(:guard_failure) do
+          benchmark(**args) { instance.call }
+        end
+
+        # If result is a GuardError, a guard failed - wrap in failure Response
+        result = Response.new(false, nil, result) if result.is_a?(Servus::Support::Errors::GuardError)
 
         after_call(result, instance)
 

data/lib/servus/config.rb

@@ -44,14 +44,29 @@ module Servus
     # @return [Boolean] true to validate, false to skip validation
     attr_accessor :strict_event_validation
 
+    # The directory where guard classes are located.
+    #
+    # Defaults to `Rails.root/app/guards` in Rails applications.
+    #
+    # @return [String] the guards directory path
+    attr_accessor :guards_dir
+
+    # Whether to include the default built-in guards (EnsurePresent, EnsurePositive).
+    #
+    # @return [Boolean] true to include default guards, false to exclude them
+    attr_accessor :include_default_guards
+
     # Initializes a new configuration with default values.
     #
     # @api private
     def initialize
-      @events_dir = 'app/events'
-      @schemas_dir = 'app/schemas'
+      @guards_dir   = 'app/guards'
+      @events_dir   = 'app/events'
+      @schemas_dir  = 'app/schemas'
       @services_dir = 'app/services'
+
       @strict_event_validation = true
+      @include_default_guards  = true
     end
 
     # Returns the full path to a service's schema file.

data/lib/servus/events/emitter.rb

@@ -118,9 +118,6 @@ module Servus
         end
       end
 
-      # Instance methods for emitting events during service execution
-      private
-
       # Emits events for a specific trigger with the given result.
       #
       # @param trigger [Symbol] the trigger type (:success, :failure, :error!)
@@ -134,6 +131,9 @@ module Servus
         end
       end
 
+      # Instance methods for emitting events during service execution
+      private
+
       # Builds the event payload using the configured payload builder or defaults.
       #
       # @param emission [Hash] the emission configuration

data/lib/servus/guard.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Servus
+  # Base class for guards that encapsulate validation logic with rich error responses.
+  #
+  # Guard classes define reusable validation rules with declarative metadata and
+  # localized error messages. They provide a clean, performant alternative to
+  # scattering validation logic throughout services.
+  #
+  # @example Basic guard
+  #   class SufficientBalanceGuard < Servus::Guard
+  #     http_status 422
+  #     error_code 'insufficient_balance'
+  #
+  #     message "Insufficient balance: need %{required}, have %{available}" do
+  #       {
+  #         required: amount,
+  #         available: account.balance
+  #       }
+  #     end
+  #
+  #     def test(account:, amount:)
+  #       account.balance >= amount
+  #     end
+  #   end
+  #
+  # @example Using a guard in a service
+  #   class TransferService < Servus::Base
+  #     def call
+  #       enforce_sufficient_balance!(account: from_account, amount: amount)
+  #       # ... perform transfer ...
+  #       success(result)
+  #     end
+  #   end
+  #
+  # @see Servus::Guards
+  # @see Servus::Base
+  class Guard
+    class << self
+      # Executes a guard and throws :guard_failure with the guard's error if validation fails.
+      #
+      # This is the bang (!) execution method that halts execution on failure.
+      # The caller is responsible for catching the thrown error and handling it.
+      #
+      # @param guard_class [Class] the guard class to execute
+      # @param kwargs [Hash] keyword arguments for the guard
+      # @return [void] returns nil if guard passes
+      # @throw [:guard_failure, GuardError] if guard fails
+      #
+      # @example
+      #   Servus::Guard.execute!(EnsurePositive, amount: 100)  # passes, returns nil
+      #   Servus::Guard.execute!(EnsurePositive, amount: -10) # throws :guard_failure
+      def execute!(guard_class, **)
+        guard = guard_class.new(**)
+        return if guard.test(**)
+
+        throw(:guard_failure, guard.error)
+      end
+
+      # Executes a guard and returns boolean result without throwing.
+      #
+      # This is the predicate (?) execution method for conditional checks.
+      #
+      # @param guard_class [Class] the guard class to execute
+      # @param kwargs [Hash] keyword arguments for the guard
+      # @return [Boolean] true if guard passes, false otherwise
+      #
+      # @example
+      #   Servus::Guard.execute?(EnsurePositive, amount: 100) # => true
+      #   Servus::Guard.execute?(EnsurePositive, amount: -10) # => false
+      def execute?(guard_class, **)
+        guard_class.new(**).test(**)
+      end
+
+      # Declares the HTTP status code for API responses.
+      #
+      # @param status [Integer] the HTTP status code
+      # @return [void]
+      #
+      # @example
+      #   class MyGuard < Servus::Guard
+      #     http_status 422
+      #   end
+      def http_status(status)
+        @http_status_code = status
+      end
+
+      # Returns the HTTP status code.
+      #
+      # @return [Integer, nil] the HTTP status code or nil if not set
+      attr_reader :http_status_code
+
+      # Declares the error code for API responses.
+      #
+      # @param code [String] the error code
+      # @return [void]
+      #
+      # @example
+      #   class MyGuard < Servus::Guard
+      #     error_code 'insufficient_balance'
+      #   end
+      def error_code(code)
+        @error_code_value = code
+      end
+
+      # Returns the error code.
+      #
+      # @return [String, nil] the error code or nil if not set
+      attr_reader :error_code_value
+
+      # Declares the message template and data block.
+      #
+      # The template can be a String (static or with %{} interpolation),
+      # a Symbol (I18n key), a Proc (dynamic), or a Hash (inline translations).
+      #
+      # The block provides data for message interpolation and is evaluated
+      # in the guard instance's context.
+      #
+      # @param template [String, Symbol, Proc, Hash] the message template
+      # @yield block that returns a Hash of interpolation data
+      # @return [void]
+      #
+      # @example With string template
+      #   message "Balance must be at least %{minimum}" do
+      #     { minimum: 100 }
+      #   end
+      #
+      # @example With I18n key
+      #   message :insufficient_balance do
+      #     { required: amount, available: account.balance }
+      #   end
+      def message(template, &block)
+        @message_template = template
+        @message_block    = block if block_given?
+      end
+
+      # Returns the message template.
+      #
+      # @return [String, Symbol, Proc, Hash, nil] the message template
+      attr_reader :message_template
+
+      # Returns the message data block.
+      #
+      # @return [Proc, nil] the message data block
+      attr_reader :message_block
+
+      # Hook called when a class inherits from Guard.
+      #
+      # Automatically defines guard methods on the Servus::Guards module.
+      #
+      # @param subclass [Class] the inheriting class
+      # @return [void]
+      # @api private
+      def inherited(subclass)
+        super
+        register_guard_methods(subclass)
+      end
+
+      # Defines bang and predicate methods on Servus::Guards for the guard class.
+      #
+      # Creates two methods:
+      #   - enforce_<name>! (throws :guard_failure on validation failure)
+      #   - check_<name>? (returns boolean)
+      #
+      # @param guard_class [Class] the guard class to register
+      # @return [void]
+      # @api private
+      #
+      # @example
+      #   # For SufficientBalanceGuard, creates:
+      #   #   enforce_sufficient_balance!(account:, amount:)
+      #   #   check_sufficient_balance?(account:, amount:)
+      def register_guard_methods(guard_class)
+        return unless guard_class.name
+
+        base_name = derive_method_name(guard_class)
+
+        # Define bang method (throws on failure)
+        Servus::Guards.define_method("enforce_#{base_name}!") do |**kwargs|
+          Servus::Guard.execute!(guard_class, **kwargs)
+        end
+
+        # Define predicate method (returns boolean)
+        Servus::Guards.define_method("check_#{base_name}?") do |**kwargs|
+          Servus::Guard.execute?(guard_class, **kwargs)
+        end
+      end
+
+      # Converts a guard class name to a method name.
+      #
+      # Strips the 'Guard' suffix and converts to snake_case.
+      # The resulting name is used with 'enforce_' and 'check_' prefixes.
+      #
+      # @param guard_class [Class] the guard class
+      # @return [String] the base method name (without enforce_/check_ prefix or ! or ?)
+      # @api private
+      #
+      # @example
+      #   derive_method_name(SufficientBalanceGuard) # => "sufficient_balance"
+      #   derive_method_name(PresenceGuard) # => "presence"
+      def derive_method_name(guard_class)
+        class_name = guard_class.name.split('::').last
+        class_name.gsub(/Guard$/, '')
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                  .downcase
+      end
+    end
+
+    attr_reader :kwargs
+
+    # Initializes a new guard instance with the provided arguments.
+    #
+    # @param kwargs [Hash] keyword arguments for the guard
+    def initialize(**kwargs)
+      @kwargs = kwargs
+    end
+
+    # Tests whether the guard passes.
+    #
+    # Subclasses must implement this method with explicit keyword arguments
+    # that define the guard's contract.
+    #
+    # @return [Boolean] true if the guard passes, false otherwise
+    # @raise [NotImplementedError] if not implemented by subclass
+    #
+    # @example
+    #   def test(account:, amount:)
+    #     account.balance >= amount
+    #   end
+    def test
+      raise NotImplementedError, "#{self.class} must implement #test"
+    end
+
+    # Returns the formatted error message.
+    #
+    # Uses {Servus::Support::MessageResolver} to resolve the template and
+    # interpolate data from the message block.
+    #
+    # @return [String] the formatted error message
+    # @see Servus::Support::MessageResolver
+    def message
+      Servus::Support::MessageResolver.new(
+        template: self.class.message_template,
+        data: self.class.message_block ? instance_exec(&self.class.message_block) : {},
+        i18n_scope: 'guards'
+      ).resolve(context: self)
+    end
+
+    # Returns a GuardError instance configured with this guard's metadata.
+    #
+    # Called when a guard fails to create the error that gets thrown.
+    # The caller decides how to handle the error (e.g., wrap in a failure response).
+    #
+    # @return [Servus::Support::Errors::GuardError] the error instance
+    def error
+      Servus::Support::Errors::GuardError.new(
+        message,
+        code: self.class.error_code_value || 'validation_failed',
+        http_status: self.class.http_status_code || 422
+      )
+    end
+
+    # Provides convenience access to kwargs as methods.
+    #
+    # This allows the message data block to access parameters directly
+    # (e.g., `amount` instead of `kwargs[:amount]`).
+    #
+    # @param method_name [Symbol] the method name
+    # @param args [Array] method arguments
+    # @param block [Proc] method block
+    # @return [Object] the value from kwargs
+    # @raise [NoMethodError] if the method is not found
+    # @api private
+    def method_missing(method_name, *args, &)
+      kwargs[method_name] || super
+    end
+
+    # Checks if the guard responds to a method.
+    #
+    # @param method_name [Symbol] the method name
+    # @param include_private [Boolean] whether to include private methods
+    # @return [Boolean] true if the method exists or is in kwargs
+    # @api private
+    def respond_to_missing?(method_name, include_private = false)
+      kwargs.key?(method_name) || super
+    end
+  end
+end

data/lib/servus/guards/falsey_guard.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Servus
+  module Guards
+    # Guard that ensures all specified attributes on an object are falsey.
+    #
+    # @example Single attribute
+    #   enforce_falsey!(on: user, check: :banned)
+    #
+    # @example Multiple attributes (all must be falsey)
+    #   enforce_falsey!(on: post, check: [:deleted, :hidden, :flagged])
+    #
+    # @example Conditional check
+    #   if check_falsey?(on: user, check: :suspended)
+    #     # user is not suspended
+    #   end
+    class FalseyGuard < Servus::Guard
+      http_status 422
+      error_code 'must_be_falsey'
+
+      message '%<class_name>s.%<failed_attr>s must be falsey (got %<value>s)' do
+        message_data
+      end
+
+      # Tests whether all specified attributes are falsey.
+      #
+      # @param on [Object] the object to check
+      # @param check [Symbol, Array<Symbol>] attribute(s) to verify
+      # @return [Boolean] true if all attributes are falsey
+      def test(on:, check:)
+        Array(check).all? { |attr| !on.public_send(attr) }
+      end
+
+      private
+
+      # Builds the interpolation data for the error message.
+      #
+      # @return [Hash] message interpolation data
+      def message_data
+        object = kwargs[:on]
+        failed = find_failing_attribute(object, Array(kwargs[:check]))
+        {
+          class_name: object.class.name,
+          failed_attr: failed,
+          value: object.public_send(failed).inspect
+        }
+      end
+
+      # Finds the first attribute that fails the falsey check.
+      #
+      # @param object [Object] the object to check
+      # @param checks [Array<Symbol>] attributes to check
+      # @return [Symbol] the first failing attribute
+      def find_failing_attribute(object, checks)
+        checks.find { |attr| !!object.public_send(attr) }
+      end
+    end
+  end
+end

data/lib/servus/guards/presence_guard.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Servus
+  module Guards
+    # Guard that ensures all provided values are present (not nil or empty).
+    #
+    # This is a flexible guard that accepts any number of keyword arguments
+    # and validates that all values are present.
+    #
+    # @example Basic usage
+    #   class MyService < Servus::Base
+    #     def call
+    #       enforce_presence!(user: user, account: account)
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example Single value
+    #   enforce_presence!(email: email)
+    #
+    # @example Multiple values
+    #   enforce_presence!(user: user, account: account, device: device)
+    #
+    # @example Conditional check
+    #   if check_presence?(user: user)
+    #     # user is present
+    #   end
+    class PresenceGuard < Servus::Guard
+      http_status 422
+      error_code 'must_be_present'
+
+      message '%<key>s must be present (got %<value>s)' do
+        message_data
+      end
+
+      # Tests whether all provided values are present.
+      #
+      # A value is considered present if it is not nil and not empty
+      # (for values that respond to empty?).
+      #
+      # @param values [Hash] keyword arguments to validate
+      # @return [Boolean] true if all values are present
+      def test(**values)
+        values.all? { |_, value| present?(value) }
+      end
+
+      private
+
+      # Builds the interpolation data for the error message.
+      #
+      # @return [Hash] message interpolation data
+      def message_data
+        failed_key, failed_value = find_failing_entry
+
+        {
+          key: failed_key,
+          value: failed_value.inspect
+        }
+      end
+
+      # Finds the first key-value pair that fails the presence check.
+      #
+      # @return [Array<Symbol, Object>] the failing key and value
+      def find_failing_entry
+        kwargs.find { |_, value| !present?(value) }
+      end
+
+      # Checks if a value is present (not nil and not empty).
+      #
+      # @param value [Object] the value to check
+      # @return [Boolean] true if present
+      def present?(value)
+        return false if value.nil?
+        return !value.empty? if value.respond_to?(:empty?)
+
+        true
+      end
+    end
+  end
+end

data/lib/servus/guards/state_guard.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Servus
+  module Guards
+    # Guard that ensures an attribute matches an expected value or one of several allowed values.
+    #
+    # @example Single expected value
+    #   enforce_state!(on: order, check: :status, is: :pending)
+    #
+    # @example Multiple allowed values (any match passes)
+    #   enforce_state!(on: account, check: :status, is: [:active, :trial])
+    #
+    # @example Conditional check
+    #   if check_state?(on: order, check: :status, is: :shipped)
+    #     # order is shipped
+    #   end
+    class StateGuard < Servus::Guard
+      http_status 422
+      error_code 'invalid_state'
+
+      message '%<class_name>s.%<attr>s must be %<expected>s (got %<actual>s)' do
+        message_data
+      end
+
+      # Tests whether the attribute matches the expected value(s).
+      #
+      # @param on [Object] the object to check
+      # @param check [Symbol] the attribute to verify
+      # @param is [Object, Array] expected value(s) - passes if attribute matches any
+      # @return [Boolean] true if attribute matches expected value(s)
+      def test(on:, check:, is:) # rubocop:disable Naming/MethodParameterName
+        Array(is).include?(on.public_send(check))
+      end
+
+      private
+
+      # Builds the interpolation data for the error message.
+      #
+      # @return [Hash] message interpolation data
+      def message_data
+        object   = kwargs[:on]
+        attr     = kwargs[:check]
+        expected = kwargs[:is]
+
+        {
+          attr: attr,
+          class_name: object.class.name,
+          actual: object.public_send(attr),
+          expected: format_expected(expected)
+        }
+      end
+
+      # Formats the expected value(s) for the error message.
+      #
+      # @param expected [Object, Array] the expected value(s)
+      # @return [String] formatted expected value(s)
+      def format_expected(expected)
+        expected.is_a?(Array) ? "one of #{expected.join(', ')}" : expected.to_s
+      end
+    end
+  end
+end